tutorial.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Welcome to the Skyrmions3D package. This is a package designed to help make the creation,\n",
    "manipulation, dynamics and plotting of Skyrmions in the Skyrme model of nuclear physics.\n",
    "\n",
    "# 1. GETTING STARTED\n",
    "\n",
    "We first need to import the `Skyrmions3D` package and the `GLMakie` package, which is used for\n",
    "plotting. Additionally, we'll tell our editor to *use* GLMakie. This is a bit awkward,\n",
    "but the many commands below should mean that it is turned on on all OSs."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "]add https://github.com/chrishalcrow/Skyrmions3D.jl.git"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "using Skyrmions3D\n",
    "\n",
    "using GLMakie\n",
    "GLMakie.activate!()\n",
    "Makie.inline!(false)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before getting started, let's try and make a \"Makie\" window. This is important for some\n",
    "more advanced features of Skyrmions3D. The following line should generate a _new window_."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "display(plot( rand(3), rand(3) ) )"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If it does not, try this"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "display(GLMakie.Screen(), plot( rand(3), rand(3) ) )"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " Later, when we plot, please use whichever line worked for you\n",
    "\n",
    "# 2. Setting up your Skyrmion, grid and parameters\n",
    "\n",
    "In this code, your Skyrme field is contained in a structure which also contains the\n",
    "grid that your field lives on. The structure also contains the parameters of the model.\n",
    "Here's an example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_skyrmion = Skyrmion( [40, 40, 40], [0.2, 0.2, 0.2] );"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This generates a Skyrme field on a 40^3 grid with 0.2 lattice spacing. Another:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_skyrmion = Skyrmion( [40, 40, 40], [0.2, 0.2, 0.2], mpi = 1.0, Fpi=186, ee=4.0, boundary_conditions=\"periodic\");"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This sets some parameters too and the periodicity of the fields.\n",
    "You can check all the properties of the Skyrmion using overview"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "overview(my_skyrmion)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can change all the parameters using the set! functions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "set_mpi!(my_skyrmion, 0.5)\n",
    "set_Fpi!(my_skyrmion, 100)\n",
    "set_ee!(my_skyrmion, 6.5)\n",
    "set_lattice!(my_skyrmion, [60,60,60], [0.2,0.2,0.2])\n",
    "set_periodic!(my_skyrmion)\n",
    "# set_neumann!(my_skyrmion) # you can also make Neumann boundary conditions!\n",
    "# set_dirichlet!(my_skyrmion)\n",
    "\n",
    "overview(my_skyrmion)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note: whenever you are confused about a function you can use ?function_name\n",
    "\n",
    "# 3. Initialising Rational Map skyrmions\n",
    "\n",
    "Let's now make a Rational Map skyrmion. To do this we can pass the numerator and\n",
    "denomenator of a Rational Map."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "p4(z) = z^4 + 2.0*sqrt(3.0)*im*z^2 + 1.0;\n",
    "q4(z) = z^4 - 2.0*sqrt(3.0)*im*z^2 + 1.0;\n",
    "f4(r) = pi*exp( -(r.^3)./12.0 )\n",
    "\n",
    "make_rational_map!(my_skyrmion, p4, q4, f4)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can calculate properties of the skyrmion using the following functions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "println(Baryon(my_skyrmion))\n",
    "Energy(my_skyrmion)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Without a profile function, the make_rational_map! function will find an OK approximate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "make_rational_map!(my_skyrmion, p4, q4; baryon=4)\n",
    "Energy(my_skyrmion)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "...and the energy of this was smaller than the other one. Excellent!\n",
    "\n",
    "We can take a look by plotting the baryon density. (Remember, this should pop up in a seperate window!)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_baryon_density(my_skyrmion)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There is also a function for making a product of several RM skyrmions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "p1(z) = z; q1(z) = 1; f1(r) = 4*atan(exp(-r));\n",
    "p2(z) = z^2; q2(z) = 1; f2(r) = 4*atan(exp(-0.7*r));\n",
    "X_list = [ [ p1, q1, f1, [0.0,0.0,1.5], 0.0, [0.0,0.0,1.0], 0.0, [0.0,0.0,1.0] ], [ p2, q2, f2, [0.0,0.0,-1.5], pi, [1.0,0.0,0.0], 0.0, [0.0,0.0,1.0] ] ]\n",
    "\n",
    "make_RM_product!(my_skyrmion, X_list)\n",
    "\n",
    "plot_baryon_density(my_skyrmion, iso_value=1.0)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 4. Calculating skyrmion properties\n",
    "\n",
    "As well as Energy and Baryon number, we can calculate many other things. First, we can look at moments using the moment` keyword"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "Energy(my_skyrmion, moment=2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can be easier to compare to other work by using Physical units on. Let's do this"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "set_physical!(my_skyrmion,true)\n",
    "Energy(my_skyrmion)\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "... and let's turn it off again"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "set_physical!(my_skyrmion,false)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also get a density if you'd like"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "baryon_density = Baryon(my_skyrmion, density=true);"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Most of the properties needed for physics are in the `compute_current` function (thanks to Alberto for the suggestion). You can find the moments of inertia"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "U = compute_current(my_skyrmion, label=\"uMOI\")\n",
    "W = compute_current(my_skyrmion, label=\"wMOI\")\n",
    "V = compute_current(my_skyrmion, label=\"vMOI\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The other currents currently included are the u and w Axial currents\n",
    "\n",
    "compute_current(my_skyrmion, label=\"uAxial\")\n",
    "compute_current(my_skyrmion, label=\"wAxial\")\n",
    "\n",
    "# as well as the stress tensor\n",
    "\n",
    "compute_current(my_skyrmion, label=\"stress\")\n",
    "\n",
    "# and the Noether iso and Axial currents.\n",
    "\n",
    "compute_current(my_skyrmion, label=\"NoetherIso\")\n",
    "compute_current(my_skyrmion, label=\"NoetherAxial\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These are all defined in the technical notes (coming soon!) and will be updated to work with physical units soon...\n",
    "\n",
    "All these functions work with moment and density. Let's find the density of the (3,3) component of the second moment of U"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "U33_density = compute_current(my_skyrmion, label=\"uMOI\", indices=[3,3], density=true, moment=2);\n",
    "\n",
    "# which we can plot...\n",
    "\n",
    "volume(U33_density[1,1,:,:,:], algorithm=:iso, isorange=1, isovalue=10)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cool! Find out more about plotting by Googling `Makie'.\n",
    "\n",
    "# 5. Initialising ADHM skyrmions\n",
    "\n",
    "Another way to create is to make ADHM skyrmion using Quaternions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "B=3\n",
    "\n",
    "adhm_data = [ Quaternion(0.0,0.0,0.0,0.0) for a in 1:B+1, b in 1:B  ]\n",
    "\n",
    "lam = 1.0\n",
    "\n",
    "adhm_data[1,1] = Quaternion(lam, 0.0, 0.0, 0.0)\n",
    "adhm_data[1,2] = Quaternion(0.0, lam, 0.0, 0.0)\n",
    "adhm_data[1,3] = Quaternion(0.0, 0.0, lam, 0.0)\n",
    "\n",
    "adhm_data[2,2] = Quaternion(0.0, 0.0, lam, 0.0)\n",
    "adhm_data[2,3] = Quaternion(0.0, lam, 0.0, 0.0)\n",
    "\n",
    "adhm_data[3,1] = Quaternion(0.0, 0.0, lam, 0.0)\n",
    "adhm_data[3,3] = Quaternion(lam, 0.0, 0.0, 0.0)\n",
    "\n",
    "adhm_data[4,1] = Quaternion(0.0, lam, 0.0, 0.0)\n",
    "adhm_data[4,2] = Quaternion(lam, 0.0, 0.0, 0.0)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The make_ADHM! function is similar to the make_rational_map! function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "make_ADHM!(my_skyrmion,adhm_data)\n",
    "plot_baryon_density(my_skyrmion, iso_value=2.0)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 6. Transforming data\n",
    "\n",
    "One of the most important things we can do is transform our skyrmions. That means translating, rotating and isorotating. Functions which end in ! modify the underlying field"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "translate_sk!(my_skyrmion, [1.0,0.0,0.0])\n",
    "rotate_sk!(my_skyrmion, pi/8, [0.0,0.0,1.0])\n",
    "isorotate_sk!(my_skyrmion, pi, [1.0,0.0,0.0])\n",
    "\n",
    "plot_baryon_density(my_skyrmion, iso_value=2.0)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or if you don't use a !, you can make new skyrmions. This is good for making something using the product approximation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "skyrmion_1 = translate_sk(my_skyrmion, [1.0,0.0,0.0]);\n",
    "skyrmion_2 = translate_sk(my_skyrmion, [-3.0,0.0,0.0]);\n",
    "\n",
    "skyrmion_3 = product_approx(skyrmion_1, skyrmion_2);\n",
    "\n",
    "plot_baryon_density(skyrmion_3, iso_value=2.0)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Looks like the skyrmions are a bit squished. This is reflected in their baryon number:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "Baryon(skyrmion_3)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You'll need to try a bigger grid!\n",
    "\n",
    "Skyrmions are quite large objects. A 40^3 skyrmion takes up 4MB of RAM. You can clear them using `Nothing`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "skyrmion_1 = Nothing\n",
    "skyrmion_2 = Nothing\n",
    "skyrmion_3 = Nothing"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 7. Flowing data\n",
    "\n",
    "Let's start fresh with a new my_skyrmion:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_skyrmion = Skyrmion( 40, 0.2 );\n",
    "\n",
    "p4(z) = z^4 + 3.0*sqrt(3.0)*im*z^2 + 1.0;\n",
    "q4(z) = z^4 - 3.0*sqrt(3.0)*im*z^2 + 1.0;\n",
    "\n",
    "make_rational_map!(my_skyrmion, p4, q4)\n",
    "\n",
    "plot_baryon_density(my_skyrmion)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can flow this using arrested Newton flow. You can flow for a set numbers of steps"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "arrested_newton_flow!(my_skyrmion, steps=100)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The error is given by the maximum absolute value of the variation. You can also make the flow tell you the energy/error at some intervals using `checks`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "arrested_newton_flow!(my_skyrmion, steps=100, checks=10)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another option is to stop after you reach some numerical tolerance"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "arrested_newton_flow!(my_skyrmion, tolerance=0.3, checks=10)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The error in arrested Newton flow fluctuates a lot. This is in contrast to gradient flow"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gradient_flow!(my_skyrmion, steps=500, checks=50)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Again, you can set a tolerance instead"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gradient_flow!(my_skyrmion, tolerance=0.0075, checks=50)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that we've never set the time step. The algorithm picks a reasonable choice. But you might want to set it yourself, you can do this as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gradient_flow!(my_skyrmion, tolerance=0.01, checks=10, dt=0.01)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Oh! That time step was too big, and it has error'd. Maybe we can salvage this..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gradient_flow!(my_skyrmion, steps=100, checks=25)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Not this time... Let's start again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "make_rational_map!(my_skyrmion, p4, q4)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can have a bit more fun by using the interactive_flow feature"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "interactive_flow(my_skyrmion)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Much more fun!\n",
    "\n",
    "That's all for this tutorial. There are a few features hidden in the ?help.\n",
    "If you have naming, features or usage feedback, please let me know!\n",
    "Once it's an official package (hopefully soon) lots of my decisions will be\n",
    "baked in for a long time!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Julia 1.9.0",
   "language": "julia",
   "name": "julia-1.9"
  },
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "1.9.0"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}