Repository: Qiskit/qiskit

Issue:
Documentation for `QuantumCircuit.assign_parameters` seems to be wrong
<!-- ⚠️ If you do not respect this template, your issue will be closed -->
<!-- ⚠️ Make sure to browse the opened and closed issues -->

### 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](https://qiskit.org/documentation/stubs/qiskit.circuit.QuantumCircuit.html#qiskit.circuit.QuantumCircuit.assign_parameters), 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

```python
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'.


Discussion:
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.

```python
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()
```

Resolving patch:
diff --git a/qiskit/circuit/library/n_local/n_local.py b/qiskit/circuit/library/n_local/n_local.py
--- a/qiskit/circuit/library/n_local/n_local.py
+++ b/qiskit/circuit/library/n_local/n_local.py
@@ -21,7 +21,6 @@
 from qiskit.circuit.quantumregister import QuantumRegister
 from qiskit.circuit import Instruction, Parameter, ParameterVector, ParameterExpression
 from qiskit.circuit.parametertable import ParameterTable
-from qiskit.utils.deprecation import deprecate_arguments
 
 from ..blueprintcircuit import BlueprintCircuit
 
@@ -793,12 +792,10 @@ def add_layer(
 
         return self
 
-    @deprecate_arguments({"param_dict": "parameters"})
     def assign_parameters(
         self,
         parameters: Union[dict, List[float], List[Parameter], ParameterVector],
         inplace: bool = False,
-        param_dict: Optional[dict] = None,
     ) -> Optional[QuantumCircuit]:
         """Assign parameters to the n-local circuit.
 
diff --git a/qiskit/circuit/quantumcircuit.py b/qiskit/circuit/quantumcircuit.py
--- a/qiskit/circuit/quantumcircuit.py
+++ b/qiskit/circuit/quantumcircuit.py
@@ -31,7 +31,7 @@
 from qiskit.qasm.qasm import Qasm
 from qiskit.qasm.exceptions import QasmError
 from qiskit.circuit.exceptions import CircuitError
-from qiskit.utils.deprecation import deprecate_function, deprecate_arguments
+from qiskit.utils.deprecation import deprecate_function
 from .parameterexpression import ParameterExpression
 from .quantumregister import QuantumRegister, Qubit, AncillaRegister, AncillaQubit
 from .classicalregister import ClassicalRegister, Clbit
@@ -2128,10 +2128,7 @@ def _unsorted_parameters(self):
 
         return parameters
 
-    @deprecate_arguments({"param_dict": "parameters"})
-    def assign_parameters(
-        self, parameters, inplace=False, param_dict=None
-    ):  # pylint: disable=unused-argument
+    def assign_parameters(self, parameters, inplace=False):
         """Assign parameters to new parameters or values.
 
         The keys of the parameter dictionary must be Parameter instances in the current circuit. The
@@ -2143,11 +2140,9 @@ def assign_parameters(
                 parameter values. If a dict, it specifies the mapping from ``current_parameter`` to
                 ``new_parameter``, where ``new_parameter`` can be a new parameter object or a
                 numeric value. If an iterable, the elements are assigned to the existing parameters
-                in the order they were inserted. You can call ``QuantumCircuit.parameters`` to check
-                this order.
+                in the order of ``QuantumCircuit.parameters``.
             inplace (bool): If False, a copy of the circuit with the bound parameters is
                 returned. If True the circuit instance itself is modified.
-            param_dict (dict): Deprecated, use ``parameters`` instead.
 
         Raises:
             CircuitError: If parameters is a dict and contains parameters not present in the
@@ -2238,8 +2233,7 @@ def assign_parameters(
                 bound_circuit._assign_parameter(self.parameters[i], value)
         return None if inplace else bound_circuit
 
-    @deprecate_arguments({"value_dict": "values"})
-    def bind_parameters(self, values, value_dict=None):  # pylint: disable=unused-argument
+    def bind_parameters(self, values):
         """Assign numeric parameters to values yielding a new circuit.
 
         To assign new Parameter objects or bind the values in-place, without yielding a new
@@ -2247,7 +2241,6 @@ def bind_parameters(self, values, value_dict=None):  # pylint: disable=unused-ar
 
         Args:
             values (dict or iterable): {parameter: value, ...} or [value1, value2, ...]
-            value_dict (dict): Deprecated, use ``values`` instead.
 
         Raises:
             CircuitError: If values is a dict and contains parameters not present in the circuit.


Test patch: