added: XY advection dynamics example

[pankajpopli]

We solve 2D vector field which follows the following equation

$$\begin{aligned} \partial_t ~\vec{p} & = J~\nabla^2\vec{p} + A (\vec{p}\cdot\vec{\nabla})\vec{p} + \Gamma~(\alpha-|\vec{p}|^2)\vec{p}\\\ \end{aligned}$$

Which is essentially a classical XY model plus advection.
Here $\vec{p} = (p_x(x,y,t), p_y(x,y,t)$ is a function of space and time.

[navidcy]

Hi @pankajpopli! thanks for the contribution!

Could you please include a small description in the first comment of this PR explaining a bit more what this example solves/demonstrates? Personally, I don't really understand even what equations the example is solving from the phrase "solving a 2D vectorial field (XY+advection)". I tried to add your example in the list of literated examples so I could have a look at the literated version but that didn't work for me.. :(

[pankajpopli]

I have now corrected the docs and it should compile correctly. Since I am new to contributing on GitHub, I apologize if I am not following the guidelines. In that case, please advise.

[navidcy]

I have now corrected the docs and it should compile correctly. Since I am new to contributing on GitHub, I apologize if I am not following the guidelines. In that case, please advise.

Don't worry about that!

Good. Probably the docs will fail because I noticed you used Plots.jl for plotting while we currently use Makie. But I can help with that.

I saw you updated the first post to add the equation! Thanks!

[glwagner]

Wikipedia entry for XY model: https://en.wikipedia.org/wiki/Classical_XY_model

Feel free to give a better citation for XY model if it's out there.

[pankajpopli]

These two should suffice, a landmark paper and a landmark book :)

[1] Kosterlitz, J. M.; Thouless, D. J. (1973), "Ordering, metastability and phase transitions in two-dimensional systems", Journal of Physics C: Solid State Physics, 6 (7): 1181–1203,

[2] P. Chaikin and T. Lubensky, Principles of Condensed Matter Physics (Cambridge Press, Cambridge, 1995).

[pankajpopli]

please add one more
[3] P. C. Hohenberg and B. I. Halperin, "Theory of dynamic critical phenomena", Rev. Mod. Phys. 49, 435, July 1977

[pankajpopli]

sorry for the installments but this paper should be added as well

[4] John Toner and Yuhai Tu, "Long-Range Order in a Two-Dimensional Dynamical XY Model: How Birds Fly Together", Phys. Rev. Lett. 75, 4326, December 1995

[pankajpopli]

added: References and CairoMakie

[navidcy]

Thanks for that! Sorry haven’t had time to have a closer look yet!

[pankajpopli]

let me update XYAdvection.jl by XYAdvection.md

[navidcy]

@pankajpopli, I had a look at the module and the example and I have a few general remarks.

1. The XYadvection module does not follow the style of other modules (e.g. the OneDShallowWater example or the Diffusion module or the modules included, e.g, in GeophysicalFlows.jl or PassiveTracerFlows.jl.

2. I don't understand the need to define methods like set_2Dgrid which basically returns the grid (same for set_Vars or set_Params).

3. Coding style: We strive to have a homogeneous coding style. This includes spaces after commas, colons, or semicolons. Also we usually omit the indentation for eveything between

module XYAdvection

end # end module

4. I built the docs using

   julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'; JULIA_DEBUG=Documenter julia --project=docs docs/make.jl
   

   and then opened the example but I saw it does not include much or any documentation.

5. I don't understand the docstrings that mention "to be called from main". What is "main"?

6. run_and_save: functions like that we leave for the user to deal with at the level of their script. In that note, it should not be part of the module in src/XYAdvection.jl but rather part of the examples/XYadvection.jl?

[navidcy]

Also we should add tests for the XYadvection module. Is there any known solution (even for a simple case, e.g. with some of the coefficients zero) that we could include as part of the tests?

[pankajpopli]

Many thanks for the remarks and suggestions!

I am first trying to cast the XYAdvection.jl in lines with diffusion.jl or "Linear rotating shallow water dynamics"

I initially intended it to be a default module of FourierFlows.jl in the beginning but I agree with your last comment now.

There are few tests for the equation, where two topological defects merge with each other giving an ordered state. Not sure if that would suffice the tests...new to Julia, please advice

[navidcy]

Many thanks for the remarks and suggestions!

I am first trying to cast the XYAdvection.jl in lines with diffusion.jl or "Linear rotating shallow water dynamics"

I initially intended it to be a default module of FourierFlows.jl in the beginning but I agree with your last comment now.

There are few tests for the equation, where two topological defects merge with each other giving an ordered state. Not sure if that would suffice the tests...new to Julia, please advice

Let's leave the tests for last. I now noticed that neither the Diffusion module nor the OneDShallowWater example have tests associated with them.

Do you think you'd go for a module in src + an example that demonstrates it or something like OneDShallowWater which is like the two above in one?