{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Magnetic Fields - All About\n",
    "\n",
    "This is all about the types of magnetic fields that are available in OSCARS.  This includes:\n",
    "\n",
    "* Uniform fields\n",
    "* Gaussian fields\n",
    "* Undulator Fields\n",
    "* Importing field data from files\n",
    "* Python function for magnetic field\n",
    "* Combining different fields\n",
    "\n",
    "You can also rotate and translate any field easily as is shown in several of the examples.\n",
    "\n",
    "There are several ways to import field data.  For 2D and 3D grids the grid must be regular.  For 1D spatial data you may import non-equidistant points."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "ename": "ModuleNotFoundError",
     "evalue": "No module named 'oscars'",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mModuleNotFoundError\u001b[0m                       Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-1-e640548b7f5c>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[1;32m      3\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      4\u001b[0m \u001b[0;31m# Import the OSCARS SR module\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 5\u001b[0;31m \u001b[0;32mimport\u001b[0m \u001b[0moscars\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0msr\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      6\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      7\u001b[0m \u001b[0;31m# Import OSCARS plots (matplotlib)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;31mModuleNotFoundError\u001b[0m: No module named 'oscars'"
     ]
    }
   ],
   "source": [
    "# matplotlib plots inline\n",
    "%matplotlib inline\n",
    "\n",
    "# Import the OSCARS SR module\n",
    "import oscars.sr\n",
    "\n",
    "# Import OSCARS plots (matplotlib)\n",
    "from oscars.plots_mpl import *"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Create a new OSCARS SR object\n",
    "osr = oscars.sr.sr()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Uniform Field\n",
    "\n",
    "A uniform field can be specified for all space or in a given *width*.  The *width* input list is like a vector representing the length and direction of the field.  It will be centered at [0, 0, 0] unless translated\n",
    "\n",
    "add_bfield_uniform can be thought of as a box where *width* are the dimensions.  If any dimension is 0 it is infinite in that dimension."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Clear any previous fields and add a constant magnetic field of 0.4 [T]\n",
    "# in the negative Y-direction with a length of 1m in the Z-direction\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_uniform(bfield=[0, -0.4, 0], width=[0, 0, 0.5])\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# The same field as above, but translated in space\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_uniform(bfield=[0, -0.4, 0], width=[0, 0, 0.5], translation=[0, 0, 0.3])\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# The same field as above, but on a different axis\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_uniform(bfield=[0, 0, -0.4], width=[0, 0.5, 0])\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr, axis='Y')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# You can also rotate the field and plot it as a function of a line through any two points\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_uniform(bfield=[0, 0, 4], width=[1, 2, 1], rotations=[0, 0, osr.pi()/4])\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr, -2, 2, axis='Y')\n",
    "plot_bfield(osr, between_two_points=[[-1, -1, 0], [1, 1, 0]])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Gaussian Field\n",
    "\n",
    "This is a gaussian field in 3D.  One can specify the 'sigma' in 1 2, or 3 dimensions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# This is a gaussian with one dimension specified.\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_gaussian(bfield=[0, 1, 0], sigma=[0, 0, 0.1], translation=[0, 0, 0.2])\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# This is a gaussian with 3 dimensions specified\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_gaussian(bfield=[1, 2, 3], sigma=[0.05, 0.05, 0.3])\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr, axis='X')\n",
    "plot_bfield(osr, axis='Y')\n",
    "plot_bfield(osr, axis='Z')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# One can also rotate and translate the gaussian object\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_gaussian(bfield=[1, 2, 0], sigma=[0.05, 0.05, 0.3], rotations=[0, osr.pi()/2, 0], translation=[0, -0.2, 0])\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr, axis='X', ylim=[-2, 2])\n",
    "plot_bfield(osr, axis='Y', ylim=[-2, 2])\n",
    "plot_bfield(osr, axis='Z', ylim=[-2, 2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Undulator Field\n",
    "\n",
    "It is simple to create a basic undulator field with termination using 'add_undulator'.  You must specify the period (given as a vector), the number of periods, and the peak bfield"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# This is the basic planer undulator field\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0, 0, 0.050], nperiods=21)\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr, -1, 1, axis='Z')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# This is the basic planer undulator field where the axis is in an arbitrary direction\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0.050, 0, 0.050], nperiods=21)\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr, between_two_points=[[-1, 0, -1], [1, 0, 1]])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# This is the field of an EPU.  Simply add two undulator fields offset in phase\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0, 0, 0.100], nperiods=11, phase=-osr.pi()/4)\n",
    "osr.add_bfield_undulator(bfield=[1, 0, 0], period=[0, 0, 0.100], nperiods=11, phase=+osr.pi()/4)\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# One can also rotat and translate an undulator field\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_undulator(bfield=[1, 2, 3], period=[0, 0, 0.050], nperiods=21, rotations=[0, 0, osr.pi()/2.], translation=[0, 0, -0.3])\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# One can also create a tapered undulator field\n",
    "# The 'taper' is input as percent per meter\n",
    "\n",
    "# This is the basic planer undulator field with taper (highly exaggerated for display purposes)\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0, 0, 0.050], nperiods=21, taper=0.40)\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Importing Data\n",
    "\n",
    "OSCARS supports several basic data formats for importing.  We are interested in supporting more.\n",
    "\n",
    "One basic format ('OSCARS1D') is where you have the magnetic field (1, 2, or 3D) given as a function of position and your file format lists rows of (for instance) 'Z Bx By Bz'.  In this case, specify X, Y, or Z, and whichever of the B's you have in the format field: iformat='Z Bx By Bz'.\n",
    "\n",
    "OSCARS format:\n",
    "Has 10 lines of header information, followed by lines consisting of 'Bx By Bz'.  You must specify iformat='OSCARS'.  The header is as follows:\n",
    "* Comment line\n",
    "* Initial X position\n",
    "* Step size in X\n",
    "* Number of points in X\n",
    "* Initial Y position\n",
    "* Step size in Y\n",
    "* Number of points in Y\n",
    "* Initial Z position\n",
    "* Step size in Z\n",
    "* Number of points in Z\n",
    "\n",
    "OSCARS also supports iformat='SPECTRA' and iformat='SRW'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# To illustrate the basic 3D format let's create a data file, then import it.\n",
    "# It will be plotted before and after the import\n",
    "\n",
    "# Create an undulator field\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_undulator(bfield=[1, 0, 0], period=[0, 0, 0.050], nperiods=11)\n",
    "plot_bfield(osr, -1, 1, axis='Z')\n",
    "\n",
    "# Now write the field to a file\n",
    "osr.write_bfield(ofile='AAMagneticFields_OSCARS.dat', oformat='OSCARS', xlim=[-1, 1], nx=2, ylim=[-1, 1], ny=2, zlim=[-1, 1], nz=5000)\n",
    "   \n",
    "\n",
    "# Clear fields and import the field from the file created above\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_file(ifile='AAMagneticFields_OSCARS.dat', iformat='OSCARS')\n",
    "\n",
    "plot_bfield(osr, -1, 1, axis='Z')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# To illustrate the basic 1D format let's create a data file, then import it.\n",
    "# It will be plotted before and after the import\n",
    "\n",
    "# Create an undulator field\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0, 0, 0.05], nperiods=31)\n",
    "plot_bfield(osr, -1, 1, axis='Z')\n",
    "\n",
    "# Now write the field to a file\n",
    "osr.write_bfield(ofile='AAMagneticFields_OSCARS1D.dat', oformat='OSCARS1D Z By Bx Bz', zlim=[-1, 1], nz=5000)   \n",
    "\n",
    "# Clear fields and import the field from the file created above, additionally you can scale the input\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_file(ifile='AAMagneticFields_OSCARS1D.dat', iformat='OSCARS1D Z By Bx Bz', scale=[1, 0.1])\n",
    "\n",
    "plot_bfield(osr, -1, 1, axis='Z')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# OSCARS supports import and exporting the SPECTRA format.\n",
    "# It will be plotted before and after the import\n",
    "\n",
    "# Make an undulator field\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0, 0, 0.050], nperiods=11)\n",
    "plot_bfield(osr)\n",
    "\n",
    "# Now write the field to a file\n",
    "osr.write_bfield(ofile='AAMagneticFields_SPECTRA.dat', oformat='SPECTRA', xlim=[-1, 1], nx=2, ylim=[-1, 1], ny=2, zlim=[-1, 1], nz=5000)\n",
    "\n",
    "# Clear fields and import the field from the file created above\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_file(ifile='AAMagneticFields_SPECTRA.dat', iformat='SPECTRA')\n",
    "\n",
    "plot_bfield(osr)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# OSCARS supports import and exporting an SRW format.\n",
    "# It will be plotted before and after the import\n",
    "\n",
    "# Make an undulator field\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_undulator(bfield=[1, 1, 0], period=[0, 0, 0.050], nperiods=11)\n",
    "plot_bfield(osr)\n",
    "\n",
    "# Now write the field to a file\n",
    "osr.write_bfield(ofile='AAMagneticFields_SPECTRA.dat', oformat='SRW', xlim=[-1, 1], nx=2, ylim=[-1, 1], ny=2, zlim=[-1, 1], nz=5000)\n",
    "\n",
    "# Clear fields and import the field from the file created above\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_file(ifile='AAMagneticFields_SPECTRA.dat', iformat='SRW')\n",
    "\n",
    "plot_bfield(osr)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# One can also rotate and translate on importing a field file\n",
    "\n",
    "# Create an undulator field\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_undulator(bfield=[0, 1, 0], period=[0, 0, 0.050], nperiods=11)\n",
    "plot_bfield(osr)\n",
    "\n",
    "# Now write the field to a file.  If you don't require a dimension you can leave it off\n",
    "osr.write_bfield(ofile='AAMagneticFields_OSCARS.dat', oformat='OSCARS', zlim=[-1, 1], nz=5000)\n",
    "\n",
    "# Clear fields and import the field from the file created above\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_file(ifile='AAMagneticFields_OSCARS.dat', iformat='OSCARS', rotations=[0, 0, osr.pi()/4], translation=[0, 0, 0.4])\n",
    "\n",
    "plot_bfield(osr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Python Function for a Field\n",
    "\n",
    "You can make your own python function and import it as a magnetic field.  All you need is a function which has 4 arguments: x, y, z, t.  *t* is not used at the moment but will be in future versions so it is required here for compatibility.  The function must return the BField in 3-dimensions as a list [Bx, By, Bz]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Define a field function for use with OSCARS\n",
    "def MyField (x, y, z, t):\n",
    "    \"\"\"User defined magnetic field in python function.  Must return a list: [Bx, By, Bz]\"\"\"\n",
    "    \n",
    "    if z >= -0.75 and z < -0.50:\n",
    "        return [0, 0, -1]\n",
    "    elif z >= -0.50 and z < 0.50:\n",
    "        return [0, 0, 4*z*z]\n",
    "    elif z >= 0.50 and z < 0.75:\n",
    "        return [0, 0, -1]\n",
    "    return [0, 0, 0]\n",
    "\n",
    "# Add the field function to oscars and plot it\n",
    "osr.clear_bfields()\n",
    "osr.add_bfield_function(MyField)\n",
    "plot_bfield(osr, -1, 1, axis='Z')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Combined Fields\n",
    "\n",
    "Add as many fields as you like to OSCARS"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "osr.clear_bfields()\n",
    "osr.add_bfield_uniform(bfield=[0, 0, 4], width=[1, 2, 1])\n",
    "osr.add_bfield_gaussian(bfield=[1, 2, 0], sigma=[0.05, 0.05, 0.03])\n",
    "osr.add_bfield_gaussian(bfield=[1, 2, 0], sigma=[0.05, 0.05, 0.03], translation=[0, 0, -0.3])\n",
    "osr.add_bfield_undulator(bfield=[1, 2, 3], period=[0, 0, 0.050], nperiods=5, translation=[0, 0, 0.4])\n",
    "\n",
    "# Plot the field if you like\n",
    "plot_bfield(osr, -1, 1, axis='X')\n",
    "plot_bfield(osr, -1, 1, axis='Y')\n",
    "plot_bfield(osr, -1, 1, axis='Z')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}