tutorial/2-Creating Your Own Initial Conditions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Terminologies\n",
    "\n",
    "<img src=\"https://github.com/dorisjlee/remote/blob/master/astroSim-tutorial-img/terminology.jpg?raw=true\",width=20%>\n",
    "- __Domain__ (aka Grids): the whole simulation box.\n",
    "- __Block__(aka Zones): group of cells that make up a larger unit so that it is more easily handled. If the code is run in parallel, you could have one processor assigned to be in charge to work on several blocks (specified by iProcs,jProcs,kProcs in flash.par). In FLASH, the default block size in flash is $2^3$ = 8 cells. This means that level 0 in the AMR is 8 cells and so forth.\n",
    "\n",
    "<img src=\"https://github.com/dorisjlee/remote/blob/master/astroSim-tutorial-img/level_cells.jpg?raw=true\",width=20%>\n",
    "- __Cells__ : basic units that contain information about the fluid variables (often called primitives: $\\rho$, $P$, $v_{x,y,z}$,$B_{x,y,z}$)\n",
    "- __Ghost cells__ (abbrev as ``gc`` in FLASH): Could be thought of as an extra layer of padding outside the simulation domain. The alues of these gcs are mostly determined by what the boundary conditions you chose. Generally, you won't have to mess with these when specifying the initial conditions.\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Simulation_initBlock.F90"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "Simulation_initBlock is called by each block. First we compute the center based on the dimensions of the box (in cgs) from flash.par:\n",
    "~~~fortran\n",
    "center = abs(xmin-xmax)/2.\n",
    "~~~\n",
    "    \n",
    "\n",
    "We loop through all the coordinates of the cell within each block. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "~~~fortran\n",
    "    do k = blkLimits(LOW,KAXIS),blkLimits(HIGH,KAXIS)\n",
    "         ! get the coordinates of the cell center in the z-direction\n",
    "         zz = zCoord(k)-center\n",
    "         do j = blkLimits(LOW,JAXIS),blkLimits(HIGH,JAXIS)\n",
    "            ! get the coordinates of the cell center in the y-direction\n",
    "            yy = yCoord(j)-center\n",
    "            do i = blkLimits(LOW,IAXIS),blkLimits(HIGH,IAXIS)\n",
    "               ! get the cell center, left, and right positions in x\n",
    "               xx  = xCenter(i)-center\n",
    "~~~"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "``xCenter,yCoord,zCoord`` are functions that return the cell position (in cgs) given its cell index. These calculations are based on treating the bottom left corner of the box as the origin, so we minus the box center to get the origin to be at the center, as shown in Fig 3."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"https://github.com/dorisjlee/remote/blob/master/astroSim-tutorial-img/user_coord.png?raw=true\",width=200,height=200>\n",
    "__Fig 3: The corrected ``xx,yy,zz`` are physical positions measured from the origin.__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Given the cell positions, you can specify values for initializing the fluid variables. \n",
    "The fluid variables are stored inside the local variables (called rhoZone,presZone,velxZone, velyZone,velzZone in the example) which are then transferred into to the cell one at a time using the method Grid_putData:\n",
    "\n",
    "~~~fortran\n",
    "    call Grid_putPointData(blockId, CENTER, DENS_VAR, EXTERIOR, axis, rhoZone)\n",
    "~~~ \n",
    "           \n",
    "For example, you may have an analytical radial density distribution ($\\rho= Ar^2$) that you would like to initialize the sphere with: \n",
    "~~~fortran\n",
    "    rr = sqrt(xx**2 + yy**2 + zz**2)\n",
    "    rhoZone = A*rr**2\n",
    "~~~\n",
    "Or maybe your initial conditions can not be expressed in closed form,then you could also read in precomputed-values for each cell. This optional tutorial will explain how to do linear interpolation to setup the numerical solution of the Lane-Emden Sphere. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding new RuntimeParameters to be read into Simulation_initBlock.F90"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we have already saw, to compute the center of the box, I need to read in the dimensions of the box (``xmin,xmax``) from flash.par. Some runtime parameters are used by other simulation modules and some are specific to the problem and defined by the users. \n",
    "\n",
    "To add in a new runtime parameter: \n",
    "\n",
    "1) In ``Simulation_data.F90``, declare the variables to store these runtime parameters:\n",
    "~~~fortran\n",
    "      real, save :: fattening_factor,beta_param,xmin,xmax\n",
    "~~~\n",
    "2) In ``Simulation_init.F90``, read in the values of the runtime parameter:\n",
    "~~~fortran   \n",
    "      call RuntimeParameters_get('xmin',xmin)\n",
    "      call RuntimeParameters_get('xmax',xmax)\n",
    "~~~\n",
    "3) In ``Simulation_initBlock.F90``, use the data:\n",
    "~~~fortran\n",
    "      use Simulation_data, ONLY:  xmin,xmax\n",
    "~~~\n",
    "Note you should __NOT__ declare ``real::xmin,xmax`` again inside ``Simulation_initBlock.F90``, otherwise, the values that you read in will be overridden."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}