docs: add documentation for tunable parameters (re-)ordering

Author: AayushSabharwal

docs/src/basics/FAQ.md

@@ -244,3 +244,62 @@ D = Differential(x)
 @variables y(x)
 @named sys = ODESystem([D(y) ~ x], x)
 ```
+
+## Ordering of tunable parameters
+
+Tunable parameters are floating point parameters, not used in callbacks and not marked with `tunable = false` in their metadata. These are expected to be used with AD
+and optimization libraries. As such, they are stored together in one `Vector{T}`. To obtain the ordering of tunable parameters in this buffer, use:
+
+```@docs
+tunable_parameters
+```
+
+If you have an array in which a particular dimension is in the order of tunable parameters (e.g. the jacobian with respect to tunables) then that dimension of the
+array can be reordered into the required permutation using the symbolic variables:
+
+```@docs
+reorder_dimension_by_tunables!
+reorder_dimension_by_tunables
+```
+
+For example:
+
+```@example reorder
+using ModelingToolkit
+
+@parameters p q[1:3] r[1:2, 1:2]
+
+@named sys = ODESystem(Equation[], ModelingToolkit.t_nounits, [], [p, q, r])
+sys = complete(sys)
+```
+
+The canonicalized tunables portion of `MTKParameters` will be in the order of tunables:
+
+```@example reorder
+using SciMLStructures: canonicalize, Tunable
+
+ps = MTKParameters(sys, [p => 1.0, q => [2.0, 3.0, 4.0], r => [5.0 6.0; 7.0 8.0]])
+arr = canonicalize(Tunable(), ps)[1]
+```
+
+We can reorder this to contain the value for `p`, then all values for `q`, then for `r` using:
+
+```@example reorder
+reorder_dimension_by_tunables(sys, arr, [p, q, r])
+```
+
+This also works with interleaved subarrays of symbolics:
+
+```@example reorder
+reorder_dimension_by_tunables(sys, arr, [q[1], r[1, :], q[2], r[2, :], q[3], p])
+```
+
+And arbitrary dimensions of higher dimensional arrays:
+
+```@example reorder
+highdimarr = stack([i * arr for i in 1:5]; dims = 1)
+```
+
+```@example reorder
+reorder_dimension_by_tunables(sys, highdimarr, [q[1:2], r[1, :], q[3], r[2, :], p]; dim = 2)
+```