example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To begin, we import the package, buckinghampy.\n",
    "I know, the name is terrible.\n",
    "\n",
    "There is also a submodule of buckinghampy which as a lot of commonly used parameters, though nothing stops you from defining your own parameters.\n",
    "\n",
    "Finally, we import some IPython display functions which will help with rendering the results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import buckinghampy\n",
    "from buckinghampy.parameters import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As a first application, we would like to find the nondimnensionalization of the basic Navier-Stokes equation:\n",
    "\n",
    "\\begin{equation}\n",
    "\\frac{\\partial {\\bf u}}{\\partial t} + {\\bf u} \\cdot \\nabla {\\bf u} = - \\nabla P + \\eta \\nabla^2 {\\bf u}\n",
    "\\end{equation}\n",
    "\n",
    "Here the fluid has density $\\rho$, viscosity $\\eta$, and we imagine that it is being driven by some velocity $u$ over some lengthscale $L$.\n",
    "\n",
    "This is a total of four paramters, which we can put into a list and give to buckinghampy:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "parameters = [density, length, velocity, viscosity]\n",
    "nondimensional_numbers = buckinghampy.find_nondimensional_numbers(parameters)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function ```buckinghampy.find_nondimensional_numbers()``` takes a list of parameters and returns an appropriate set of nondimensional numbers for those parameters.  These numbers are returned as strings which can be output to LaTeX in IPython:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$$\\frac{ \\eta}{ \\rho L u}$$"
      ],
      "text/plain": [
       "[<buckinghampy.nondimensional.NondimensionalNumber at 0x7ff929762240>]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nondimensional_numbers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You may recognize this as the the inverse of the Reynolds number. This brings us to an important point: in general, the nondimensionalization of a set of parameters is nonunique. There are some groupings which are conventional, but buckinghampy might not find those. For problems with more than one nondimensional number, the problem becomes harder: not only are inverses and powers of nondimensional numbers allowed, but so are any multiplicative combinations of the different numbers.\n",
    "\n",
    "We can look at another example from radiative physics. Consider the blackbody radiation spectrum of an object. We expect this problem to depend on the light frequency, the speed of light, Planck's constant, the Boltzmann constant, and the temperature:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$$\\frac{ h \\nu}{ k_{B} T}$$"
      ],
      "text/plain": [
       "[<buckinghampy.nondimensional.NondimensionalNumber at 0x7ff912f312e8>]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "parameters = [boltzmann,temperature, planck, speed_of_light, frequency]\n",
    "nondimensional_numbers = buckinghampy.find_nondimensional_numbers(parameters)\n",
    "\n",
    "nondimensional_numbers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The nondimensionalization recovers the argument of the exponential in a Boltzmann distribution.\n",
    "\n",
    "\n",
    "As an example of a more complicated system, consider the equations for Rayleigh-Bernard convection in a Boussinesq fluid:\n",
    "\n",
    "\\begin{equation}\n",
    "-\\nabla P + \\eta \\nabla^2 {\\bf u} + \\delta \\rho {\\bf g} = 0\n",
    "\\end{equation}\n",
    "\n",
    "\\begin{equation}\n",
    "\\nabla \\cdot {\\bf u} = 0\n",
    "\\end{equation}\n",
    "\n",
    "\\begin{equation}\n",
    "\\frac{\\partial T}{\\partial t} + {\\bf u} \\cdot \\nabla T = \\kappa \\nabla^2 T\n",
    "\\end{equation}\n",
    "\n",
    "where $T$ is temperature, $\\kappa$ is the thermal diffusivity, $g$ is gravity, $\\delta \\rho = -\\rho_0 \\alpha T$ is the density variations driving buoyancy, $L$ is the layer depth, and $\\Delta T$ is the temperature drop across the convecting layer.\n",
    "\n",
    "An accounting of the paramters in the set of equations finds $\\Delta T$, $\\rho_0$, $g$, $\\alpha$, $\\kappa$, $\\eta$, and $L$.  However in the governing equations $\\rho_0$, $g$, and $\\alpha$ only appear when multiplied together, so they should really only count for one parameter, which we will define as the \"buoyancy parameter.\"\n",
    "\n",
    "Using the Parameter class in buckinghampy.parameters we can define new paramters for $\\Delta T$ and the buoyancy paramter (which are not predefined in the module)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "buoyancy_parameter = Parameter( '\\\\rho_0 \\\\alpha g', {'kg' :  1,\\\n",
    "                                                      'm'  : -2,\\\n",
    "                                                      's'  : -2,\\\n",
    "                                                      'K'  : -1})\n",
    "delta_T = Parameter( '\\\\Delta T', {'K' : 1})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now create a paramters object for this system and find the nondimensional numbers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$$\\frac{ \\kappa \\eta}{ \\rho_0 \\alpha g \\Delta T L^{3}}$$"
      ],
      "text/plain": [
       "[<buckinghampy.nondimensional.NondimensionalNumber at 0x7ff912f314e0>]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "parameters = [buoyancy_parameter, delta_T, length, thermal_diffusivity, viscosity]\n",
    "nondimensional_numbers = buckinghampy.find_nondimensional_numbers(parameters)\n",
    "\n",
    "nondimensional_numbers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Hey, would you look at that, it's one over the Rayleigh number! As a side note, if we had not combined some parameters into the buoyancy parameter, we would have gotten some extra nondimensional numbers:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$$ \\alpha \\Delta T, \\frac{ \\kappa^{2}}{ g L^{3}}, \\frac{ \\eta^{2}}{ g \\rho^{2} L^{3}}$$"
      ],
      "text/plain": [
       "[<buckinghampy.nondimensional.NondimensionalNumber at 0x7ff912f31828>,\n",
       " <buckinghampy.nondimensional.NondimensionalNumber at 0x7ff912f31cf8>,\n",
       " <buckinghampy.nondimensional.NondimensionalNumber at 0x7ff912f31d30>]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "parameters = [thermal_expansivity, gravity, density, delta_T, length, thermal_diffusivity, viscosity]\n",
    "nondimensional_numbers = buckinghampy.find_nondimensional_numbers(parameters)\n",
    "\n",
    "nondimensional_numbers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Okay, that is a bit uglier, but some judicious multiplying and dividing of these nondimensional numbers will allow you to find the Rayleigh number, density deficit number, and the Prandtl number. These nondimensional numbers would all appear in more complete versions of the governing equations, but the Boussinesq approximation allows for the combination of paramters into the buoyancy parameter above, and the resulting simplification of the nondimensionalization."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.6.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}