Document that constants can only contain 1D array

[unalmis]

Otherwise you get weird optimization errors.
Linking relevant comments:
#1288 (comment)
#1290 (comment)

[dpanici]

Can you post a MWE? so we can see the error, and also try it with the omnigenity optimization?

[dpanici]

There may be something more than just having a 1D array, like it may have to also be used in a specific way for the error to occur. I say this because in PlasmaVesselDistance we have a 2D array in constants and I have not noticed this issue (the issue being, running the optimization twice in one python session causes some error relating to array size right?)

[unalmis]

My second linked comment would seem to disagree with that, as even if I don't use the constants array, for example by setting the objective.compute method to be a one liner that returns an array filled with the value 1.0, the same issue occurs.

The MWE is to take any objective function, for example ripple on #1290 , change the compute function to whatever you want, and the issue is reproduced if constants holds anything other than 1d arrays.

[unalmis]

issue being, running the optimization twice in one python session causes some error relating to array size right?

The error has always been the same as #1288 . The array size issue I mention there is my interpretation of jax's oblivious error message, which seems to have been a useful interpretation because ensuring constants contains only 1d arrays, in particular no 2d or tuples, avoided one way the issue pops up.

[dpanici]

# this has NO error
import desc.examples
from desc.objectives import ObjectiveFunction, PlasmaVesselDistance
from desc.grid import LinearGrid
from desc.optimize import Optimizer
eq = desc.examples.get("HELIOTRON")

constraints = ()  
# circular surface
a = 0.5
R0 = 10
surf = eq.surface.copy()
surf.change_resolution(M=1, N=1)

grid = LinearGrid(M=eq.M , N=eq.N, NFP=eq.NFP)
obj = PlasmaVesselDistance(
    surface=surf,
    eq=eq,
    target=0.25,
    surface_grid=grid,
    plasma_grid=grid,
    use_signed_distance=True,surface_fixed=True
)
objective = ObjectiveFunction((obj,))

optimizer = Optimizer("lsq-exact")
(eq, ), _ = optimizer.optimize(
    (eq, ), objective, constraints, verbose=0, maxiter=2, ftol=0, xtol=1e-9
)

eq = eq.copy()
obj = PlasmaVesselDistance(
    surface=surf,
    eq=eq,
    target=0.25,
    surface_grid=grid,
    plasma_grid=grid,
    use_signed_distance=True,surface_fixed=True
)
objective = ObjectiveFunction((obj,))
(eq, ), _ = optimizer.optimize(
    (eq, ), objective, constraints, verbose=0, maxiter=2, ftol=0, xtol=1e-9
)


print(objective.objectives[0].constants["surface_coords"].shape)

The above snippet outputs this (no error) on master (and on ripple too):

DESC version 0.12.3+1138.g533793e27,using JAX backend, jax version=0.4.31, jaxlib version=0.4.30, dtype=float64
Using device: CPU, with 4.63 GB available memory
(175, 3)