examples/Introduction to NodePy.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook shows a few features of the NodePy package."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Instantiating a method and inspecting its properties"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can load a pre-defined RK method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nodepy import rk\n",
    "import numpy as np\n",
    "\n",
    "rk4 = rk.loadRKM('RK44')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or create a custom method by entering the coefficients:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "A=np.array([[0,0],[0.5,0]])\n",
    "b=np.array([0,1.])\n",
    "rk22=rk.ExplicitRungeKuttaMethod(A,b)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can print the Butcher tableau:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(rk4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(rk22)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Plot the region of absolute stability:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rk4.plot_stability_region();"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rk22.plot_stability_region();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check the order of the method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(rk4.order())\n",
    "print(rk22.order())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Understanding Runge-Kutta order conditions\n",
    "\n",
    "Order conditions for Runge-Kutta methods are algebraic conditions on the coefficients that are necessary and sufficient in order that the local error have a certain order (in terms of the time step size).  In the theory developed by John Butcher and subsequent researchers, it has been shown that the conditions for order $p$ can be mapped 1-1 to the set of rooted trees of order $p$.  This correspondence is used in NodePy to generate order conditions.  As an illustration, here are all the rooted trees of order 6.\n",
    "\n",
    "For more on the theory of RK order conditions, see the textbook of Butcher or of Hairer & Wanner."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import nodepy.rooted_trees as rt\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "fig = rt.plot_all_trees(6)\n",
    "\n",
    "plt.setp(fig,dpi=500)\n",
    "plt.draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Practical comparison of Runge-Kutta methods\n",
    "\n",
    "NodePy includes some convenient functions for running a set of time-stepping methods on a set of initial-value problems."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Convergence test\n",
    "\n",
    "This function runs each method with a range of fixed step sizes and plots the error versus the number of derivative evaluations.  This is a commonly-used metric for deciding which method is most efficient."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import nodepy.runge_kutta_method as rk\n",
    "import nodepy.convergence as cv\n",
    "from nodepy import ivp\n",
    "\n",
    "#Load some methods:\n",
    "rk4=rk.loadRKM('RK44')\n",
    "SSP2=rk.loadRKM('SSP22')\n",
    "SSP104=rk.loadRKM('SSP104')\n",
    "\n",
    "#Define an IVP:\n",
    "myivp = ivp.load_ivp('test')\n",
    "\n",
    "cv.ctest([rk4,SSP2,SSP104], myivp, verbosity=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Performance test\n",
    "\n",
    "For methods with automatic step size control (such as embedded Runge-Kutta pairs), we can run each method with a range of prescribed error tolerances."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\"\"\"Runs a performance test over the non-stiff DETEST suite of problems\"\"\"\n",
    "from nodepy import *\n",
    "\n",
    "bs5=rk.loadRKM('BS5')\n",
    "f5=rk.loadRKM('Fehlberg45')\n",
    "dp5=rk.loadRKM('DP5')\n",
    "ivps=ivp.detest_suite()\n",
    "\n",
    "tols=list(map(lambda x:10**-x,range(4,10)))\n",
    "\n",
    "conv.ptest([bs5,dp5,f5],ivps,tols)"
   ]
  }
 ],
 "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.5"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}