resources/2022HW_dive_into_plasmapy_completed.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "# Dive into Plasmapy\n",
    "\n",
    "### Contents\n",
    "\n",
    "1. [`plasmapy.formulary` Unit Agnosticism](#plasmapy.formulary-Unit-Agnoticism)\n",
    "2. [`@validate_quantities` - The Units Enforcer](#@validate_quantites---The-Units-Enforcer)\n",
    "3. [`@particle_input`](#@particle_input)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "## `plasmapy.formulary` Unit Agnoticism\n",
    "\n",
    "`astropy.unts` (along with some magic) allowed us to develop a formulary that is agnostic to input units, and will always return values in SI units."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "import astropy.units as u\n",
    "\n",
    "from plasmapy.formulary import Debye_length"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Let's start with SI units"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "T_e = 115000 * u.K  # about 10 eV\n",
    "n_e = 2e18 * u.m**-3\n",
    "\n",
    "Debye_length(T_e=T_e, n_e=n_e)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Let's do the same calculation, but with non-SI units"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "T_e_in_eV = T_e.to(u.eV, equivalencies=u.temperature_energy())\n",
    "n_e_in_lsec3 = n_e.to(u.lsec**-3)\n",
    "\n",
    "(T_e_in_eV, n_e_in_lsec3)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "Debye_length(T_e=T_e_in_eV, n_e=n_e_in_lsec3)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "## `@validate_quantites` - The Units Enforcer\n",
    "\n",
    "The reasone we have unit agnosticism is because we have develped an units enforce.  This enforcer, `@validate_quantites`, knows how to recognize input unit types, interpret what the function is expecting, and do the proper conversion or enforcement.\n",
    "\n",
    "Let's start with a function that calculates the kinetic energy of a mass."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "def kinetic_energy_lite(mass, velocity):\n",
    "    return 0.5 * mass * velocity**2\n",
    "\n",
    "kinetic_energy_lite(mass=1233, velocity=39.34)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "But we have not unit enforement..."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "from plasmapy.utils.decorators import validate_quantities"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "kinetic_energy = validate_quantities(func=kinetic_energy_lite, mass=u.kg, velocity=u.m/u.s)\n",
    "\n",
    "kinetic_energy(mass=1233, velocity=39.34)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Now we are getting warnings that input arguments are not given with units, and the output units are a total mess."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "kinetic_energy(mass=1233 * u.kg, velocity=39.34 * u.m/u.s)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "The output units are still a mess, so we can do better..."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "kinetic_energy = validate_quantities(func=kinetic_energy_lite, mass=u.kg, velocity=u.m/u.s, validations_on_return=u.Joule)\n",
    "\n",
    "kinetic_energy(mass=1233 * u.kg, velocity=39.34 * u.m/u.s)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Much better, but we still have a hidden bug.  What happens is the mass is negative?"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "kinetic_energy(mass=-1233 * u.kg, velocity=39.34 * u.m/u.s)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Well, that does not make much sense, but `validate_quantites` can still help us out..."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "kinetic_energy = validate_quantities(\n",
    "    func=kinetic_energy_lite, \n",
    "    mass={\"units\": u.kg, \"can_be_negative\": False},\n",
    "    velocity=u.m/u.s, \n",
    "    validations_on_return=u.Joule,\n",
    ")\n",
    "\n",
    "kinetic_energy(mass=-1233 * u.kg, velocity=39.34 * u.m/u.s)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Well, that makes a lot more physical sense!\n",
    "\n",
    "We can still make this a lot cleaner by using Python's sugar syntax for decorators."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "@validate_quantities(\n",
    "    mass={\"units\": u.kg, \"can_be_negative\": False},\n",
    "    velocity=u.m/u.s, \n",
    "    validations_on_return=u.Joule,\n",
    ")\n",
    "def kinetic_energy(mass, velocity):\n",
    "    return 0.5 * mass * velocity**2\n",
    "\n",
    "# even cleaner\n",
    "\n",
    "@validate_quantities(mass={\"can_be_negative\": False})\n",
    "def kinetic_energy(mass: u.kg, velocity: u.m/u.s) -> u.Joule:\n",
    "    return 0.5 * mass * velocity**2"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "Using non-standard units"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "mass = 2718 * u.imperial.lb  # mass of a Delorean\n",
    "velocity = 88 * u.imperial.mile / u.hour\n",
    "\n",
    "kinetic_energy(mass=mass, velocity=velocity)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "## `@particle_input`\n",
    "\n",
    "Well, that was cool and all but not really usefull if we are trying to find the kinetic energy of a particle.  `plasmapy` does make this a little easier with the `Particle` class."
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "from plasmapy.particles import Particle\n",
    "\n",
    "par = Particle(\"Fe\")\n",
    "par.mass"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "kinetic_energy(mass=par.mass, velocity=velocity)"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "source": [
    "But we can do better by using the `@particle_input` decorator. "
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%% md\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "from plasmapy.particles import particle_input\n",
    "\n",
    "@validate_quantities\n",
    "@particle_input\n",
    "def kinetic_energy(velocity: u.m/u.s, particle: Particle) -> u.Joule:\n",
    "    return 0.5 * particle.mass * velocity**2"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [
    "kinetic_energy(velocity=velocity, particle=\"Fe\")\n"
   ],
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "name": "#%%\n"
    }
   }
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `plasmapy.formulary` Unit Agnoticism\n",
    "\n",
    "`astropy.unts` (along with some magic) allowed us to develop a formulary that is agnostic to input units, and will always return values in SI units."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import astropy.units as u\n",
    "\n",
    "from plasmapy.formulary import Debye_length"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's start with SI units"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "T_e = 115000 * u.K  # about 10 eV\n",
    "n_e = 2e18 * u.m**-3\n",
    "\n",
    "Debye_length(T_e=T_e, n_e=n_e)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's do the same calculation, but with non-SI units"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "T_e_in_eV = T_e.to(u.eV, equivalencies=u.temperature_energy())\n",
    "n_e_in_lsec3 = n_e.to(u.lsec**-3)\n",
    "\n",
    "(T_e_in_eV, n_e_in_lsec3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "Debye_length(T_e=T_e_in_eV, n_e=n_e_in_lsec3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `@validate_quantites` - The Units Enforcer\n",
    "\n",
    "The reasone we have unit agnosticism is because we have develped an units enforce.  This enforcer, `@validate_quantites`, knows how to recognize input unit types, interpret what the function is expecting, and do the proper conversion or enforcement.\n",
    "\n",
    "Let's start with a function that calculates the kinetic energy of a mass."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def kinetic_energy_lite(mass, velocity):\n",
    "    return 0.5 * mass * velocity**2\n",
    "\n",
    "kinetic_energy_lite(mass=1233, velocity=39.34)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But we have not unit enforement..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from plasmapy.utils.decorators import validate_quantities"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kinetic_energy = validate_quantities(func=kinetic_energy_lite, mass=u.kg, velocity=u.m/u.s)\n",
    "\n",
    "kinetic_energy(mass=1233, velocity=39.34)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we are getting warnings that input arguments are not given with units, and the output units are a total mess."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kinetic_energy(mass=1233 * u.kg, velocity=39.34 * u.m/u.s)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The output units are still a mess, so we can do better..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kinetic_energy = validate_quantities(func=kinetic_energy_lite, mass=u.kg, velocity=u.m/u.s, validations_on_return=u.Joule)\n",
    "\n",
    "kinetic_energy(mass=1233 * u.kg, velocity=39.34 * u.m/u.s)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Much better, but we still have a hidden bug.  What happens is the mass is negative?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kinetic_energy(mass=-1233 * u.kg, velocity=39.34 * u.m/u.s)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Well, that does not make much sense, but `validate_quantites` can still help us out..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kinetic_energy = validate_quantities(\n",
    "    func=kinetic_energy_lite, \n",
    "    mass={\"units\": u.kg, \"can_be_negative\": False},\n",
    "    velocity=u.m/u.s, \n",
    "    validations_on_return=u.Joule,\n",
    ")\n",
    "\n",
    "kinetic_energy(mass=-1233 * u.kg, velocity=39.34 * u.m/u.s)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Well, that makes a lot more physical sense!\n",
    "\n",
    "We can still make this a lot cleaner by using Python's sugar syntax for decorators."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@validate_quantities(\n",
    "    mass={\"units\": u.kg, \"can_be_negative\": False},\n",
    "    velocity=u.m/u.s, \n",
    "    validations_on_return=u.Joule,\n",
    ")\n",
    "def kinetic_energy(mass, velocity):\n",
    "    return 0.5 * mass * velocity**2\n",
    "\n",
    "# even cleaner\n",
    "\n",
    "@validate_quantities(mass={\"can_be_negative\": False})\n",
    "def kinetic_energy(mass: u.kg, velocity: u.m/u.s) -> u.Joule:\n",
    "    return 0.5 * mass * velocity**2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using non-standard units"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mass = 2718 * u.imperial.lb  # mass of a Delorean\n",
    "velocity = 88 * u.imperial.mile / u.hour\n",
    "\n",
    "kinetic_energy(mass=mass, velocity=velocity)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `@particle_input`\n",
    "\n",
    "Well, that was cool and all but not really usefull if we are trying to find the kinetic energy of a particle.  `plasmapy` does make this a little easier with the `Particle` class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from plasmapy.particles import Particle\n",
    "\n",
    "par = Particle(\"Fe\")\n",
    "par.mass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kinetic_energy(mass=par.mass, velocity=velocity)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But we can do better by using the `@particle_input` decorator. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from plasmapy.particles import particle_input\n",
    "\n",
    "@validate_quantities\n",
    "@particle_input\n",
    "def kinetic_energy(velocity: u.m/u.s, particle: Particle) -> u.Joule:\n",
    "    return 0.5 * particle.mass * velocity**2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kinetic_energy(velocity=velocity, particle=\"Fe\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}