Tidy up coordinate systems with explicit directions #2165

bendudson · 2020-12-05T18:50:23Z

Define the directions of the poloidal and toroidal angles more carefully, so that at each step the direction of each coordinate is clearer.

The new calculations clarify what happens when the poloidal field is negative. For the standard coordinate system (where J can be >0 or <0), the metric tensor doesn't change from what it was before. The calculation of the field line pitch and integrated shear however has been clarified (in terms of which toroidal direction is used).

A new coordinate system is defined, with the Y coordinate reversed for negative poloidal field. This always has a positive Jacobian, and some metric elements reverse sign, but has the same properties (being Clebsch).

Define the directions of the poloidal and toroidal angles more carefully, so that at each step the direction of each coordinate is clearer. The new calculations clarify what happens when the poloidal field is negative. For the standard coordinate system (where J can be >0 or <0), the metric tensor doesn't change from what it was before. The calculation of the field line pitch and integrated shear however has been clarified (in terms of which toroidal direction is used). A new coordinate system is defined, with the Y coordinate reversed for negative poloidal field. This always has a positive Jacobian, and some metric elements reverse sign, but has the same properties (being Clebsch).

ZedThree · 2020-12-07T11:36:05Z

Note, built docs are here: https://bout-dev--2165.org.readthedocs.build/en/2165/user_docs/coordinates.html

manual/sphinx/user_docs/coordinates.rst

Co-authored-by: Peter Hill <zed.three@gmail.com>

Accidentally left in factor of sigma_Btheta in metric tensor for J>0 field-aligned coordinates.

Should have Btor in e_phi direction, not e_zeta.

- In the standard BOUT++ coordinates, there is a factor of sigma_Btheta, so the sign of zShift doesn't change if Bpol is changed. - The modified coordinates with J > 0 do change sign with Bpol

Some confusion about signs in these angles, but I think this is ok now.

Missing braces, too many ticks

Should be the same for both field-aligned coordinate systems, just reversed y <-> θ

manual/sphinx/user_docs/coordinates.rst

1. Distinguish Jacobian in orthogonal (psi, theta, zeta) coordinates from Jacobian in (x,y,z) coordinates, since these differ by a sign when Bpol < 0. 2. Use η for parallel coordinate rather than y in right-handed field-aligned coordinate system.

Clarify which coordinates the J refers to

johnomotani

A couple of typos and a clarification in the review comments.

Another question: should the Laplacian and perpendicular Laplacian expressions be written in terms of metric components so that if we're in the xyz coords, they're implicitly using d/dy and g_{yz}, etc. with \sigma_{B\theta} included?

I think we're going to end up using the 'x\etaz' coordinates for simulations with negative Bp? In that case, would it be better to swap the names y<->\eta so that 'xyz' is the (always right-handed) coordinate system that we'll actually use?

manual/sphinx/user_docs/coordinates.rst

Co-authored-by: johnomotani <john.omotani@ukaea.uk>

ZedThree

LGTM, assuming @johnomotani is happy with the maths! :)

ZedThree · 2021-01-05T10:43:59Z

manual/sphinx/user_docs/coordinates.rst

+The sign of the poloidal field `{B_{\text{pol}}}` and toroidal field 
+`{B_{\text{tor}}}` can be either + or -.


Just to clarify, are the signs independent of each other? Or do they both need to be the same sign?

Ah yes, they are independent, but that could be clearer in the text

Suggested change

The sign of the poloidal field `{B_{\text{pol}}}` and toroidal field

`{B_{\text{tor}}}` can be either + or -.

The sign of the poloidal field `{B_{\text{pol}}}` and toroidal field

`{B_{\text{tor}}}` can be independently either + or -.

manual/sphinx/user_docs/coordinates.rst

Co-authored-by: Peter Hill <zed.three@gmail.com>

johnomotani

A few more minor comments...

johnomotani · 2021-01-07T14:09:59Z

manual/sphinx/user_docs/coordinates.rst

+The sign of the poloidal field `{B_{\text{pol}}}` and toroidal field 
+`{B_{\text{tor}}}` can be either + or -.


Suggested change

The sign of the poloidal field `{B_{\text{pol}}}` and toroidal field

`{B_{\text{tor}}}` can be either + or -.

The sign of the poloidal field `{B_{\text{pol}}}` and toroidal field

`{B_{\text{tor}}}` can be independently either + or -.

johnomotani · 2021-01-07T14:37:18Z

manual/sphinx/user_docs/coordinates.rst

+The `\texttt{zShift}` is used to connect grid cells along the magnetic
+field. It is the `z` angle of a point on a field line relative to a
+reference location:
+
+.. math::
+
+   \begin{aligned}
+   \texttt{zShift}\left(x, y\right) &= \int_{y = 0}^{y}\frac{{\boldsymbol{B}}\cdot\nabla z}{{\boldsymbol{B}}\cdot\nabla y} dy \\
+   &= \int_{\theta = 0}^{\theta}\frac{{\sigma_{B\theta}}{B_{\text{tor}}}{h_\theta}}{{B_{\text{pol}}}R} d\theta \\
+   &= {\sigma_{B\theta}} \int_{\theta = 0}^{\theta} \nu d\theta
+   \end{aligned}


z is the field-aligned coordinate, so isn't $B\cdot\nabla z = 0$? I think this should be the shift in \zeta-angle, etc.

Suggested change

The `\texttt{zShift}` is used to connect grid cells along the magnetic

field. It is the `z` angle of a point on a field line relative to a

reference location:

.. math::

\begin{aligned}

\texttt{zShift}\left(x, y\right) &= \int_{y = 0}^{y}\frac{{\boldsymbol{B}}\cdot\nabla z}{{\boldsymbol{B}}\cdot\nabla y} dy \\

&= \int_{\theta = 0}^{\theta}\frac{{\sigma_{B\theta}}{B_{\text{tor}}}{h_\theta}}{{B_{\text{pol}}}R} d\theta \\

&= {\sigma_{B\theta}} \int_{\theta = 0}^{\theta} \nu d\theta

\end{aligned}

The `\texttt{zShift}` is used to connect grid cells along the magnetic

field. It is the `\zeta` angle of a point on a field line relative to a

reference location:

.. math::

\begin{aligned}

\texttt{zShift}\left(x, y\right) &= \int_{y = 0}^{y}\frac{{\boldsymbol{B}}\cdot\nabla \zeta}{{\boldsymbol{B}}\cdot\nabla y} dy \\

&= \int_{\theta = 0}^{\theta}\frac{{\sigma_{B\theta}}{B_{\text{tor}}}{h_\theta}}{{B_{\text{pol}}}R} d\theta \\

&= {\sigma_{B\theta}} \int_{\theta = 0}^{\theta} \nu d\theta

\end{aligned}

B dot e_z = 0, but B dot nabla z is the toroidal field (with a +/-)

I'm not sure about that:

nabla z != nabla zeta, and B dot nabla zeta is the toroidal field (with a +/-)

we can write \vec{B} = Bp / htheta * \vec{e}_y, and e_i dot \nabla x^j = delta_i^j, so e_y dot \nabla z = 0

Isn't it B dot e_z that's !=0?

Ah yes, quite right sorry: B = nabla x cross nabla z so B dot nabla z must be zero

johnomotani · 2021-01-07T14:38:56Z

manual/sphinx/user_docs/coordinates.rst

+
+The `\texttt{ShiftAngle}` is then defined as the change in
+`\texttt{zShift}` between `y=0` and `y=2\pi`: It is the change in the
+`z` coordinate after one poloidal circuit in `y`.


Suggested change

`z` coordinate after one poloidal circuit in `y`.

`z` coordinate after one poloidal circuit in `y` and is related to the

safety factor by `\mathtt{ShiftAngle} = 2\pi q(x)`.

johnomotani · 2021-01-07T14:44:11Z

manual/sphinx/user_docs/coordinates.rst

+   \begin{aligned}
+   \boldsymbol{e}_x =& J_{x\eta z}\left(\nabla y \times \nabla z\right) = {\sigma_{B\theta}} {\boldsymbol{e}}_\psi + I{\boldsymbol{e}}_\zeta \\
+   \boldsymbol{e}_\eta =& J_{x\eta z}\left(\nabla z \times \nabla x\right) = {\sigma_{B\theta}} {\boldsymbol{e}}_\theta + \nu{\boldsymbol{e}}_\zeta \\
+   \boldsymbol{e}_z =& J_{x\eta z}\left(\nabla x \times \nabla y\right) = {\boldsymbol{e}}_\zeta
+   \end{aligned}


Need \eta instead of y in a couple of places

Suggested change

\begin{aligned}

\boldsymbol{e}_x =& J_{x\eta z}\left(\nabla y \times \nabla z\right) = {\sigma_{B\theta}} {\boldsymbol{e}}_\psi + I{\boldsymbol{e}}_\zeta \\

\boldsymbol{e}_\eta =& J_{x\eta z}\left(\nabla z \times \nabla x\right) = {\sigma_{B\theta}} {\boldsymbol{e}}_\theta + \nu{\boldsymbol{e}}_\zeta \\

\boldsymbol{e}_z =& J_{x\eta z}\left(\nabla x \times \nabla y\right) = {\boldsymbol{e}}_\zeta

\end{aligned}

\begin{aligned}

\boldsymbol{e}_x =& J_{x\eta z}\left(\nabla \eta \times \nabla z\right) = {\sigma_{B\theta}} {\boldsymbol{e}}_\psi + I{\boldsymbol{e}}_\zeta \\

\boldsymbol{e}_\eta =& J_{x\eta z}\left(\nabla z \times \nabla x\right) = {\sigma_{B\theta}} {\boldsymbol{e}}_\theta + \nu{\boldsymbol{e}}_\zeta \\

\boldsymbol{e}_z =& J_{x\eta z}\left(\nabla x \times \nabla \eta\right) = {\boldsymbol{e}}_\zeta

\end{aligned}

johnomotani · 2021-01-07T14:49:48Z

manual/sphinx/user_docs/coordinates.rst

+The `\texttt{zShift}` quantity is the `z` angle of a point on a field
+line relative to a reference location. This is a scalar which doesn't
+change if the sign of the `\eta` coordinate is reversed:
+
+.. math::
+
+   \begin{aligned}
+   \texttt{zShift}\left(x, \eta\right) = \int_{\eta = 0}^{\eta}\frac{{\boldsymbol{B}}\cdot\nabla z}{{\boldsymbol{B}}\cdot\nabla \eta} d\eta =
+   \int_{\theta = 0}^{{\sigma_{B\theta}}\theta}\frac{{\sigma_{B\theta}}{B_{\text{tor}}}{h_\theta}}{{B_{\text{pol}}}R} d\theta
+   \end{aligned}


Similar to comment above: \zeta-angle instead of z-angle

Suggested change

The `\texttt{zShift}` quantity is the `z` angle of a point on a field

line relative to a reference location. This is a scalar which doesn't

change if the sign of the `\eta` coordinate is reversed:

.. math::

\begin{aligned}

\texttt{zShift}\left(x, \eta\right) = \int_{\eta = 0}^{\eta}\frac{{\boldsymbol{B}}\cdot\nabla z}{{\boldsymbol{B}}\cdot\nabla \eta} d\eta =

\int_{\theta = 0}^{{\sigma_{B\theta}}\theta}\frac{{\sigma_{B\theta}}{B_{\text{tor}}}{h_\theta}}{{B_{\text{pol}}}R} d\theta

\end{aligned}

The `\texttt{zShift}` quantity is the `\zeta` angle of a point on a field

line relative to a reference location. This is a scalar which doesn't

change if the sign of the `\eta` coordinate is reversed:

.. math::

\begin{aligned}

\texttt{zShift}\left(x, \eta\right) = \int_{\eta = 0}^{\eta}\frac{{\boldsymbol{B}}\cdot\nabla \zeta}{{\boldsymbol{B}}\cdot\nabla \eta} d\eta =

\int_{\theta = 0}^{{\sigma_{B\theta}}\theta}\frac{{\sigma_{B\theta}}{B_{\text{tor}}}{h_\theta}}{{B_{\text{pol}}}R} d\theta

\end{aligned}

johnomotani · 2021-01-07T14:57:48Z

manual/sphinx/user_docs/coordinates.rst

@@ -226,9 +427,9 @@ magnetic field `{\boldsymbol{b}}_0` is given by

   \begin{aligned}
   \partial^0_{||}f \equiv {\boldsymbol{b}}_0 \cdot\nabla f =
-   \frac{1}{\sqrt{g_{yy}}}{\frac{\partial f}{\partial y}} = \frac{{B_{\text{pol}}}}{B{h_\theta}}{\frac{\partial f}{\partial y}}\end{aligned}
+   \frac{1}{JB}{\frac{\partial f}{\partial y}} = \frac{{B_{\text{pol}}}}{B{h_\theta}}{\frac{\partial f}{\partial y}}\end{aligned}


The middle expression (with J) is fine, but the final one should be |B_pol| for the (x,eta,z) coords. Maybe we need to define something like \sigma_y = \{\sigma_{B\theta} for xyz | +1 for x\eta z\} to use in places like this? I'll have a stab at this in a new set of comments (just to group that set of changes into one thread).

Keep track of correct signs for both x,y,z and x,eta,z coordinates. This commit goes through 'Differential operators in field-aligned coordinates', 'J x B in field-aligned coordinates' and 'Parallel current' sections.

johnomotani · 2021-01-08T00:04:14Z

Do we still need the 'Shifted radial derivatives' subsection? I guess it's for 'BOUT06-style' IncIntShear derivatives that we don't use any more (and should remove for v5?)? I've skipped checking that one...

Co-authored-by: Peter Hill <zed.three@gmail.com>

Co-authored-by: Ben Dudson <bd512@york.ac.uk> Co-authored-by: Peter Hill <zed.three@gmail.com>

Next coordinates sigma y

johnomotani

@bendudson I think we can merge this if you're happy with it.

bendudson added the work in progress Not ready for merging label Dec 5, 2020

bendudson mentioned this pull request Dec 5, 2020

Negative Jacobian boutproject/hypnotoad#56

Open

ZedThree reviewed Dec 7, 2020

View reviewed changes

manual/sphinx/user_docs/coordinates.rst Show resolved Hide resolved

ZedThree reviewed Dec 7, 2020

View reviewed changes

manual/sphinx/user_docs/coordinates.rst Outdated Show resolved Hide resolved

ZedThree reviewed Dec 7, 2020

View reviewed changes

manual/sphinx/user_docs/coordinates.rst Outdated Show resolved Hide resolved

bendudson mentioned this pull request Dec 7, 2020

Testing of Coordinates #2167

Merged

bendudson and others added 6 commits December 7, 2020 15:14

Update manual/sphinx/user_docs/coordinates.rst

442e832

Co-authored-by: Peter Hill <zed.three@gmail.com>

Update manual/sphinx/user_docs/coordinates.rst

08e0d3f

Co-authored-by: Peter Hill <zed.three@gmail.com>

Update manual/sphinx/user_docs/coordinates.rst

93ecb86

Co-authored-by: Peter Hill <zed.three@gmail.com>

Fix typo, add explanation of coordinate differences

472dbaf

Accidentally left in factor of sigma_Btheta in metric tensor for J>0 field-aligned coordinates.

Fix expression for B

c07a528

Should have Btor in e_phi direction, not e_zeta.

Add description of zShift

ddce348

- In the standard BOUT++ coordinates, there is a factor of sigma_Btheta, so the sign of zShift doesn't change if Bpol is changed. - The modified coordinates with J > 0 do change sign with Bpol

bendudson mentioned this pull request Dec 8, 2020

WIP: handling of negative poloidal field boutproject/hypnotoad#57

Open

6 tasks

bendudson added 3 commits December 8, 2020 23:00

Tidy up zShift and ShiftAngle

6b25c86

Some confusion about signs in these angles, but I think this is ok now.

Fix a couple of LaTeX issues

1a2ba7a

Missing braces, too many ticks

Add sigma_B to zShift

57d68b6

Should be the same for both field-aligned coordinate systems, just reversed y <-> θ

bendudson added documentation and removed work in progress Not ready for merging labels Dec 9, 2020

bendudson changed the title ~~WIP: Tidy up coordinate systems with explicit directions~~ Tidy up coordinate systems with explicit directions Dec 9, 2020

johnomotani reviewed Dec 10, 2020

View reviewed changes

manual/sphinx/user_docs/coordinates.rst Outdated Show resolved Hide resolved

bendudson added 2 commits December 11, 2020 14:40

Add some missing subscripts on Jacobians

f374049

Clarify which coordinates the J refers to

johnomotani reviewed Dec 12, 2020

View reviewed changes

manual/sphinx/user_docs/coordinates.rst Outdated Show resolved Hide resolved

manual/sphinx/user_docs/coordinates.rst Outdated Show resolved Hide resolved

manual/sphinx/user_docs/coordinates.rst Outdated Show resolved Hide resolved

bendudson and others added 3 commits December 14, 2020 09:46

Update manual/sphinx/user_docs/coordinates.rst

96210af

Co-authored-by: johnomotani <john.omotani@ukaea.uk>

Update manual/sphinx/user_docs/coordinates.rst

e4638a0

Co-authored-by: johnomotani <john.omotani@ukaea.uk>

Re-word description of zShift

f79530e

ZedThree previously approved these changes Jan 5, 2021

View reviewed changes

Update manual/sphinx/user_docs/coordinates.rst

f61734a

Co-authored-by: Peter Hill <zed.three@gmail.com>

bendudson dismissed ZedThree’s stale review via f61734a January 5, 2021 11:10

ZedThree previously approved these changes Jan 5, 2021

View reviewed changes

johnomotani reviewed Jan 7, 2021

View reviewed changes

johnomotani added 4 commits January 7, 2021 20:32

Correct signs in coordinates section of manual

d51a440

Keep track of correct signs for both x,y,z and x,eta,z coordinates. This commit goes through 'Differential operators in field-aligned coordinates', 'J x B in field-aligned coordinates' and 'Parallel current' sections.

Signs in 'Curvature' subsection of coordinates

60a1042

Corrections to 'Curvature from Curl(b/B)'

ec9c30e

Add missing sigma_Btheta in 'Curvature in toroidal coordinates'

3000378

johnomotani added 4 commits January 8, 2021 00:06

More small fixes for Coordinates section of manual

5c2d80b

Allow for -'ve Jacobian

02b831f

Tiny clarification

1b08814

Minor fixes in 'Derivation of operators in the BOUT++ Clebsh system'

a27b528

johnomotani mentioned this pull request Jan 8, 2021

Next coordinates sigma y #2203

Merged

johnomotani and others added 5 commits January 8, 2021 13:57

Fix use of cases environment

8f44451

Co-authored-by: Peter Hill <zed.three@gmail.com>

Fix typos found in code review

2468738

Co-authored-by: Ben Dudson <bd512@york.ac.uk> Co-authored-by: Peter Hill <zed.three@gmail.com>

Rename sigma_Btheta to sigma_Bpol

43780ea

Fix formatting of some subscripts

040c434

Merge pull request #2203 from boutproject/next-coordinates-sigma_y

80e8eb4

Next coordinates sigma y

bendudson dismissed ZedThree’s stale review via 80e8eb4 January 12, 2021 12:06

johnomotani approved these changes Mar 1, 2021

View reviewed changes

bendudson merged commit 19c3997 into next Mar 1, 2021

bendudson deleted the next-coordinates branch March 1, 2021 10:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tidy up coordinate systems with explicit directions #2165

Tidy up coordinate systems with explicit directions #2165

bendudson commented Dec 5, 2020

ZedThree commented Dec 7, 2020

johnomotani left a comment

ZedThree left a comment

ZedThree Jan 5, 2021

bendudson Jan 5, 2021

johnomotani Jan 7, 2021

johnomotani left a comment

johnomotani Jan 7, 2021

johnomotani Jan 7, 2021

bendudson Jan 7, 2021

johnomotani Jan 7, 2021

johnomotani Jan 7, 2021

bendudson Jan 7, 2021

johnomotani Jan 7, 2021

johnomotani Jan 7, 2021

johnomotani Jan 7, 2021

johnomotani Jan 7, 2021

johnomotani commented Jan 8, 2021

johnomotani left a comment

		The sign of the poloidal field `{B_{\text{pol}}}` and toroidal field
		`{B_{\text{tor}}}` can be either + or -.

	`z` coordinate after one poloidal circuit in `y`.
	`z` coordinate after one poloidal circuit in `y` and is related to the
	safety factor by `\mathtt{ShiftAngle} = 2\pi q(x)`.

Tidy up coordinate systems with explicit directions #2165

Tidy up coordinate systems with explicit directions #2165

Conversation

bendudson commented Dec 5, 2020

ZedThree commented Dec 7, 2020

johnomotani left a comment

Choose a reason for hiding this comment

ZedThree left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnomotani left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnomotani commented Jan 8, 2021

johnomotani left a comment

Choose a reason for hiding this comment