`bracket` is confusing (me)

[dschwoerer]

The Bracket operator calculates {f, g}_{xz} or 1 / sqrt(g_22) / coord->J / B * (g_22 {f, g}_{x, z} + g_23 {f, g}_{y,z} + g_12 {f, g}_{y, z})

Now I understand that they g_23 and g_12 are sometimes assumed to be zero. Am I correct in the assumption that in some grids sqrt(g_22) / J / B is unity for many tokamak grids?

Note that the documentation is wrong - the terms are included in the standard method: https://bout-dev.readthedocs.io/en/stable/user_docs/coordinates.html#the-bracket-operator-in-bout

It states to always return the first version, but that is not true for the "standard method" - which actually returns the second version.

Is it time to deprecate bracket() - and instead have a poission_bracket which is the current bracket but without the "standard" method, and arakawa as default? We could add a new ve_grad_bracket operator that always returns the second, and add maybe add different implementations that uses internally the poisson_bracket to calculate the different terms.

[bendudson]

Hi @dschwoerer I agree the operator is a bit confusing, given all the possible ways it can be implemented and terms that it may or may not include.

You're correct that sqrt(g_22) / J / B is unity for the standard BOUT++ tokamak coordinates: https://bout-dev.readthedocs.io/en/stable/user_docs/coordinates.html#equation-eq-covariantmetric2 But there is a twist: It could be +1 or -1 depending on the sign of J. It is very easy to forget that J can be negative and the coordinate system may be left-handed, so despite many attempts I am still not 100% sure that all operators are correct when J < 0. I believe BOUT++ enforces J > 0 in the input checks, which then makes simulating some cases with reversed poloidal field awkward (need to reverse the grid so Y goes anticlockwise rather than clockwise in the right hand poloidal plane).