Documentation for QuantumCircuit.assign_parameters seems to be wrong

[chris-n-self]

Information

• Qiskit Terra version: 0.17.4
• Python version: 3.9.4
• Operating system: MacOS 10.14.6

What is the current behavior?

The description of the QuantumCircuit.assign_parameters method in the docs, says that:

"If an iterable, the elements are assigned to the existing parameters in the order they were inserted. "

but this does not seem to be the behaviour of the function. Instead, if you call QuantumCircuit.parameters the parameters seem to be returned in lexical order and passing an iterable assigns elements to the existing parameters in that order. The documentation does say that the order will be specified by QuantumCircuit.parameters:

"You can call QuantumCircuit.parameters to check this order."

But the comment about this being the order the parameters were inserted is misleading.

Steps to reproduce the problem

from qiskit import QuantumCircuit
from qiskit.circuit import Parameter

circ = QuantumCircuit(4)
for idx in range(12):
    circ.ry(Parameter('p'+f'{idx}'), idx%4)
circ.draw()

print(circ.parameters)

circ2 = circ.assign_parameters([Parameter('q'+f'{idx}') for idx in range(12)])
circ2.draw()

The intended behaviour is to remap parameters so that 'p0 -> q0', 'p1 -> q1', 'p2 -> q2' etc. but because of the lexical ordering 'q2' instead replaces 'p10'.

[Cryoris]

Good catch! That's wrong, you're right. It should state

If an iterable, the elements are assigned to the existing parameters in the order of QuantumCircuit.parameters.

For you use-case, you could use a ParameterVector, then the index-order will be recognized.

from qiskit import QuantumCircuit
from qiskit.circuit import ParameterVector

p = ParameterVector('p', 12)
q = ParameterVector('q', 12)

circ = QuantumCircuit(4)
for idx in range(12):
    circ.ry(p[idx], idx%4)
circ.draw()

print(circ.parameters)

circ2 = circ.assign_parameters(q[:])
circ2.draw()