% Generated by Sphinx. \def\sphinxdocclass{report} \documentclass[letterpaper,10pt,english]{sphinxmanual} \usepackage[utf8]{inputenc} \DeclareUnicodeCharacter{00A0}{\nobreakspace} \usepackage[T1]{fontenc} \usepackage{babel} \usepackage{times} \usepackage[Bjarne]{fncychap} \usepackage{longtable} \usepackage{sphinx} \usepackage{multirow} \title{pyPLUTO Documentation} \date{November 02, 2012} \release{4-1.0} \author{Bhargav Vaidya , Denis Stepanovs} \newcommand{\sphinxlogo}{} \renewcommand{\releasename}{Release} \makeindex \makeatletter \def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax% \let\PYG@ul=\relax \let\PYG@tc=\relax% \let\PYG@bc=\relax \let\PYG@ff=\relax} \def\PYG@tok#1{\csname PYG@tok@#1\endcsname} \def\PYG@toks#1+{\ifx\relax#1\empty\else% \PYG@tok{#1}\expandafter\PYG@toks\fi} \def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{% \PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}} \def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}} \def\PYG@tok@gd{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.00,0.00}{##1}}} \def\PYG@tok@gu{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}} \def\PYG@tok@gt{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.25,0.82}{##1}}} \def\PYG@tok@gs{\let\PYG@bf=\textbf} \def\PYG@tok@gr{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}} \def\PYG@tok@cm{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}} \def\PYG@tok@vg{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}} \def\PYG@tok@m{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}} \def\PYG@tok@mh{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}} \def\PYG@tok@cs{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}\def\PYG@bc##1{\colorbox[rgb]{1.00,0.94,0.94}{##1}}} \def\PYG@tok@ge{\let\PYG@it=\textit} \def\PYG@tok@vc{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}} \def\PYG@tok@il{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}} \def\PYG@tok@go{\def\PYG@tc##1{\textcolor[rgb]{0.19,0.19,0.19}{##1}}} \def\PYG@tok@cp{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} \def\PYG@tok@gi{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.63,0.00}{##1}}} \def\PYG@tok@gh{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}} \def\PYG@tok@ni{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.84,0.33,0.22}{##1}}} \def\PYG@tok@nl{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.13,0.44}{##1}}} \def\PYG@tok@nn{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}} \def\PYG@tok@no{\def\PYG@tc##1{\textcolor[rgb]{0.38,0.68,0.84}{##1}}} \def\PYG@tok@na{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}} \def\PYG@tok@nb{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} \def\PYG@tok@nc{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}} \def\PYG@tok@nd{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.33,0.33,0.33}{##1}}} \def\PYG@tok@ne{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} \def\PYG@tok@nf{\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.49}{##1}}} \def\PYG@tok@si{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.44,0.63,0.82}{##1}}} \def\PYG@tok@s2{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}} \def\PYG@tok@vi{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}} \def\PYG@tok@nt{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.45}{##1}}} \def\PYG@tok@nv{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}} \def\PYG@tok@s1{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}} \def\PYG@tok@gp{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}} \def\PYG@tok@sh{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}} \def\PYG@tok@ow{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} \def\PYG@tok@sx{\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}} \def\PYG@tok@bp{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} \def\PYG@tok@c1{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}} \def\PYG@tok@kc{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} \def\PYG@tok@c{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}} \def\PYG@tok@mf{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}} \def\PYG@tok@err{\def\PYG@bc##1{\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{##1}}} \def\PYG@tok@kd{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} \def\PYG@tok@ss{\def\PYG@tc##1{\textcolor[rgb]{0.32,0.47,0.09}{##1}}} \def\PYG@tok@sr{\def\PYG@tc##1{\textcolor[rgb]{0.14,0.33,0.53}{##1}}} \def\PYG@tok@mo{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}} \def\PYG@tok@mi{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}} \def\PYG@tok@kn{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} \def\PYG@tok@o{\def\PYG@tc##1{\textcolor[rgb]{0.40,0.40,0.40}{##1}}} \def\PYG@tok@kr{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} \def\PYG@tok@s{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}} \def\PYG@tok@kp{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} \def\PYG@tok@w{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}} \def\PYG@tok@kt{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.13,0.00}{##1}}} \def\PYG@tok@sc{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}} \def\PYG@tok@sb{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}} \def\PYG@tok@k{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} \def\PYG@tok@se{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}} \def\PYG@tok@sd{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}} \def\PYGZbs{\char`\\} \def\PYGZus{\char`\_} \def\PYGZob{\char`\{} \def\PYGZcb{\char`\}} \def\PYGZca{\char`\^} \def\PYGZsh{\char`\#} \def\PYGZpc{\char`\%} \def\PYGZdl{\char`\$} \def\PYGZti{\char`\~} % for compatibility with earlier versions \def\PYGZat{@} \def\PYGZlb{[} \def\PYGZrb{]} \makeatother \begin{document} \maketitle \tableofcontents \phantomsection\label{index::doc} \bigskip\hrule{}\bigskip \chapter{Information} \label{index:pypluto-code}\label{index:information}\begin{quote}\begin{description} \item[{Author}] \leavevmode Bhargav Vaidya (b.vaidya at leeds.ac.uk) and Denis Stepanovs (stepanovs at mpia.de) \item[{Version}] \leavevmode 4-1.0 \item[{Date}] \leavevmode November 02, 2012 \end{description}\end{quote} \textbf{TASK :} Quick Tool for Visualization of PLUTO 4.0 code data (\href{http://adsabs.harvard.edu/abs/2007ApJS..170..228M}{Mignone2007}) \textbf{DESCRIPTION :} The code is completely written using the Python Language. Further the GUI is developed with the Tkinter Interface. \textbf{FEATURES :} 1. Completely based on Python and easy to work without need of any licenses like in IDL. 2. The GUI environment provides a tool for quick-check of data during the simulations runs. 3. The code is user friendly and allows the user to even do further plotting of contours, velocity vectors on the surface plot. Also the code can read user-defined variables. \chapter{Getting Started} \label{index:getting-started}\label{index:mignone2007} \section{Installation} \label{install:installation}\label{install::doc} After ensuring that all of the above pre-requisites are working and installed the user can download pyPLUTO-4-1.0.zip from \href{http://www.ast.leeds.ac.uk/~phybva/Bhargav\_Vaidya/Simulations.html}{here}. The code can be installed using a standard procedure. This can be done by following steps: \begin{enumerate} \item {} \textbf{Global Install} \end{enumerate} The Python version from the EPD version by default creates a PYTHONPATH. If no option is chosen for preferred path then in that case the code will be installed in that default path. This may require the user to have access to the root password: \begin{itemize} \item {} Unzip/Untar the source code : \code{unzip pyPLUTO-\textbar{}version\textbar{}.zip} or \code{tar -xvzf pyPLUTO-\textbar{}version\textbar{}.tar.gz} \item {} Enter into the directory : \code{cd pyPLUTO-\textbar{}version\textbar{}} \item {} Install the code in the default path : \code{python setup.py install} \end{itemize} \begin{enumerate} \setcounter{enumi}{1} \item {} \textbf{Local Install (Recommended)} \end{enumerate} The best practice is to create your own PYTHONPATH and do a local install in the following way: \begin{itemize} \item {} Create a directory where to store this module : \code{mkdir MyPython\_Modules} \item {} Unzip/Untar the source code : \code{unzip pyPLUTO-\textbar{}version\textbar{}.zip} or \code{tar -xvzf pyPLUTO-\textbar{}version\textbar{}.tar.gz} \item {} Enter into the directory : \code{cd pyPLUTO-\textbar{}version\textbar{}} \item {} Install the code in the directory created : \code{python setup.py install -{-}prefix=\textless{}path to MyPython\_Modules\textgreater{}} \item {} Then append the following in your .bashrc : \code{export PYTHONPATH =\textless{}path to MyPython\_Modules\textgreater{}/lib/python\textless{}ver\textgreater{}/site-packages} \end{itemize} where \textless{}ver\textgreater{} is the python version which the user have used to install the package. \begin{enumerate} \setcounter{enumi}{2} \item {} \textbf{GIT Repository} \end{enumerate} This code is also available as a git repo and can be obtained as follows : \code{git clone git://github.com/coolastro/pyPLUTO.git} After the successful installation, the user can start using GUI application by appending the \textless{}path to GUI\_pyPLUTO.py\textgreater{} into their PATH. \section{Loading the Data} \label{pload:loading-the-data}\label{pload::doc}\index{pload (class in pyPLUTO)} \begin{fulllineitems} \phantomsection\label{pload:pyPLUTO.pload}\pysiglinewithargsret{\strong{class }\code{pyPLUTO.}\bfcode{pload}}{\emph{ns}, \emph{w\_dir=None}, \emph{datatype=None}}{} This Class has all the routines loading the data from the binary files output from PLUTO Simulations. Assign an object when the data is loaded for some \emph{ns}. \textbf{Inputs:} \begin{quote} ns -- Time step of the data, data.ns.dbl or data.ns.flt w\_dir -- path to the directory which has the dbl.out(or flt.out) and the data datatype -- If the data is of `float' type then datatype = `float' else by default the datatype is set to `double'. \end{quote} \textbf{Outputs:} \begin{quote} A pyPLUTO.pload object having all the relevant information of the corresponding data file \end{quote} \textbf{Usage}: \begin{quote} \code{import pyPLUTO as pp} \code{wdir = '/path/to/the data files/'} \code{D = pp.pload(1,w\_dir=wdir)} Now D is the pyPLUTO.pload object having all the relevant information of the corresponding data file - data.0001.dbl. \end{quote} \index{data() (pyPLUTO.pload method)} \begin{fulllineitems} \phantomsection\label{pload:pyPLUTO.pload.data}\pysiglinewithargsret{\bfcode{data}}{\emph{datatype}}{} This method loads the data from the file name ``data.ns.dbl''(in case of single\_file) or ``varname.ns.dbl''(in case of multiple files). \textbf{Inputs:} \begin{quote} datatype -- If the data is of `float' type then datatype = `float' else by default the datatype is set to `double'. \end{quote} \textbf{Outputs:} \begin{quote} It returns a dictionary with all the variable names as the keys. \textbf{NOTE} All these variable names are set as attributes to the pyPLUTO.pload object like the grid() function. \end{quote} \end{fulllineitems} \index{geometry() (pyPLUTO.pload method)} \begin{fulllineitems} \phantomsection\label{pload:pyPLUTO.pload.geometry}\pysiglinewithargsret{\bfcode{geometry}}{}{} This method has the geometry information of the problem considered. \end{fulllineitems} \index{get\_varinfo() (pyPLUTO.pload method)} \begin{fulllineitems} \phantomsection\label{pload:pyPLUTO.pload.get_varinfo}\pysiglinewithargsret{\bfcode{get\_varinfo}}{\emph{datatype}}{} This method reads the dbl.out (or flt.out) and stores the information in a dictionary. \textbf{Inputs:} \begin{quote} datatype -- If the data is of `float' type then datatype = `float' else by default the datatype is set to `double'. \end{quote} \textbf{Outputs:} \begin{quote} A dictionary with the following keywords - fltype -- returns the filetype of storing data (single\_file or multiple\_file) nvar -- Number of variables allvars -- A list of variables names. Each of the variable name will be the attributes to the pyPLUTO.pload object. \end{quote} \end{fulllineitems} \index{grid() (pyPLUTO.pload method)} \begin{fulllineitems} \phantomsection\label{pload:pyPLUTO.pload.grid}\pysiglinewithargsret{\bfcode{grid}}{}{} This method returns the necessary grid information in form a dictionary after reading the grid.out. \textbf{Outputs:} \begin{quote} This function outputs a dictionary with following keys. n1 -- number of grid cells in x1 direction n2 -- number of grid cells in x2 direction n3 -- number of grid cells in x3 direction x1 -- Array x1 x2 - Array x2 x3 - Array x3 dx1 - Array dx1 dx2 - Array dx2 dx3 - Array dx3 \end{quote} \textbf{Usage:} \begin{quote} \code{import pyPLUTO as pp} \code{D = pp.pload(1)} \code{G = D.grid()} Now, G is a dictionary such that G{[}'x1'{]} will give the x-array. \textbf{NOTE} - Even x1 is set as attribute for the pyPLUTO.pload object i.e., the x-array can be obtained as D.x1. Infact all the keys of this routine are set as attributes for the pyPLUTO.pload object D. \end{quote} \end{fulllineitems} \index{time\_info() (pyPLUTO.pload method)} \begin{fulllineitems} \phantomsection\label{pload:pyPLUTO.pload.time_info}\pysiglinewithargsret{\bfcode{time\_info}}{\emph{datatype}}{} This method returns a dictionary that has the time information for the step ns. \textbf{Inputs:} \begin{quote} datatype -- If the data is of `float' type then datatype = `float' else by default the datatype is set to `double'. \end{quote} \textbf{Outputs:} \begin{quote} A dictionary which has a following keys - time -- Gets the simulation time at step ns. dt -- Get the time step dt for step ns. Nstep -- Get the value of nstep for the step ns. \end{quote} \end{fulllineitems} \end{fulllineitems} \section{Viewing the Data} \label{image:viewing-the-data}\label{image::doc}\index{Image (class in pyPLUTO)} \begin{fulllineitems} \phantomsection\label{image:pyPLUTO.Image}\pysigline{\strong{class }\code{pyPLUTO.}\bfcode{Image}} This Class has all the routines for the imaging the data and plotting various contours and fieldlines on these images. CALLED AFTER pyPLUTO.pload object is defined \index{field\_interp() (pyPLUTO.Image method)} \begin{fulllineitems} \phantomsection\label{image:pyPLUTO.Image.field_interp}\pysiglinewithargsret{\bfcode{field\_interp}}{\emph{var1}, \emph{var2}, \emph{x}, \emph{y}, \emph{dx}, \emph{dy}, \emph{xp}, \emph{yp}}{} This method interpolates value of vector fields (var1 and var2) on field points (xp and yp). The field points are obtained from the method field\_line. \textbf{Inputs:} \begin{quote} var1 -- 2D Vector field in X direction var2 -- 2D Vector field in Y direction x -- 1D X array y -- 1D Y array dx -- 1D grid spacing array in X direction dy -- 1D grid spacing array in Y direction xp -- field point in X direction yp -- field point in Y direction \end{quote} \textbf{Outputs:} \begin{quote} A list with 2 elements where the first element corresponds to the interpolate field point in `x' direction and the second element is the field point in `y' direction. \end{quote} \end{fulllineitems} \index{field\_line() (pyPLUTO.Image method)} \begin{fulllineitems} \phantomsection\label{image:pyPLUTO.Image.field_line}\pysiglinewithargsret{\bfcode{field\_line}}{\emph{var1}, \emph{var2}, \emph{x}, \emph{y}, \emph{dx}, \emph{dy}, \emph{x0}, \emph{y0}}{} This method is used to obtain field lines (same as fieldline.pro in PLUTO IDL tools). \textbf{Inputs:} \begin{quote} var1 -- 2D Vector field in X direction var2 -- 2D Vector field in Y direction x -- 1D X array y -- 1D Y array dx -- 1D grid spacing array in X direction dy -- 1D grid spacing array in Y direction x0 -- foot point of the field line in X direction y0 -- foot point of the field line in Y direction \end{quote} \textbf{Outputs:} \begin{quote} This routine returns a dictionary with keys - qx -- list of the field points along the `x' direction. qy -- list of the field points along the `y' direction. \end{quote} \textbf{Usage:} \begin{quote} See the myfieldlines routine for the same. \end{quote} \end{fulllineitems} \index{getSphData() (pyPLUTO.Image method)} \begin{fulllineitems} \phantomsection\label{image:pyPLUTO.Image.getSphData}\pysiglinewithargsret{\bfcode{getSphData}}{\emph{Data}, \emph{w\_dir=None}, \emph{datatype=None}, \emph{**kwargs}}{} This method transforms the vector and scalar fields from Spherical co-ordinates to Cylindrical. \textbf{Inputs}: \begin{quote} Data -- pyPLUTO.pload object w\_dir -- /path/to/the/working/directory/ datatype -- If the data is of `float' type then datatype = `float' else by default the datatype is set to `double'. \end{quote} \emph{Optional Keywords}: \begin{quote} rphi -- {[}Default{]} is set to False implies that the r-theta plane is transformed. If set True then the r-phi plane is transformed. x2cut -- Applicable for 3D data and it determines the co-ordinate of the x2 plane while r-phi is set to True. x3cut -- Applicable for 3D data and it determines the co-ordinate of the x3 plane while r-phi is set to False. \end{quote} \end{fulllineitems} \index{myfieldlines() (pyPLUTO.Image method)} \begin{fulllineitems} \phantomsection\label{image:pyPLUTO.Image.myfieldlines}\pysiglinewithargsret{\bfcode{myfieldlines}}{\emph{Data}, \emph{x0arr}, \emph{y0arr}, \emph{stream=False}, \emph{**kwargs}}{} This method overplots the magnetic field lines at the footpoints given by (x0arr{[}i{]},y0arr{[}i{]}). \textbf{Inputs:} \begin{quote} Data -- pyPLUTO.pload object x0arr -- array of x co-ordinates of the footpoints y0arr -- array of y co-ordinates of the footpoints stream -- keyword for two different ways of calculating the field lines. \begin{quote} True -- plots contours of rAphi (needs to store vector potential) False -- plots the fieldlines obtained from the field\_line routine. (Default option) \end{quote} \end{quote} \emph{Optional Keywords:} \begin{quote} colors -- A list of matplotlib colors to represent the lines. The length of this list should be same as that of x0arr. lw -- Integer value that determines the linewidth of each line. ls -- Determines the linestyle of each line. \end{quote} \textbf{Usage:} Assume that the magnetic field is a given as \textbf{B} = B0\$hat\{y\}\$. Then to show this field lines we have to define the x and y arrays of field foot points. \code{x0arr = linspace(0.0,10.0,20)} \code{y0arr = linspace(0.0,0.0,20)} \code{import pyPLUTO as pp} \code{D = pp.pload(45)} \code{I = pp.Image()} \code{I.myfieldlines(D,x0arr,y0arr,colors='k',ls='-{-}',lw=1.0)} \end{fulllineitems} \index{pldisplay() (pyPLUTO.Image method)} \begin{fulllineitems} \phantomsection\label{image:pyPLUTO.Image.pldisplay}\pysiglinewithargsret{\bfcode{pldisplay}}{\emph{var}, \emph{**kwargs}}{} This method allows the user to display a 2D data using the matplotlib's pcolormesh. \textbf{Inputs:} \begin{quote} var -- 2D array that needs to be displayed. \end{quote} \emph{Required Keywords:} \begin{quote} x1 -- The `x' array x2 -- The `y' array \end{quote} \emph{Optional Keywords:} \begin{quote} vmin -- The minimum value of the 2D array (Default : min(var)) vmax -- The maximum value of the 2D array (Default : max(var)) title -- Sets the title of the image. label1 -- Sets the X Label (Default: `XLabel') label2 -- Sets the Y Label (Default: `YLabel') \begin{description} \item[{cbar -- Its a tuple to set the colorbar on or off. }] \leavevmode cbar = (True,'vertical') -- Displays a vertical colorbar cbar = (True,'horizontal') -- Displays a horizontal colorbar cbar = (False,'`) -- Displays no colorbar. \end{description} \end{quote} \textbf{Usage:} \begin{quote} \code{import pyPLUTO as pp} \code{wdir = '/path/to/the data files/'} \code{D = pp.pload(1,w\_dir=wdir)} \code{I = pp.Image()} \code{f1 = figure()} \code{ax1 = f1.add\_subplot(111)} \code{I.pldisplay(D.v2,x1=D.x1,x2=D.x2,cbar=(True,'vertical'),title='Velocity',label1='Radius',label2='Height')} \end{quote} \end{fulllineitems} \index{pltSphData() (pyPLUTO.Image method)} \begin{fulllineitems} \phantomsection\label{image:pyPLUTO.Image.pltSphData}\pysiglinewithargsret{\bfcode{pltSphData}}{\emph{Data}, \emph{w\_dir=None}, \emph{datatype=None}, \emph{**kwargs}}{} This method plots the transformed data obtained from getSphData using the matplotlib's imshow \textbf{Inputs:} \begin{quote} Data -- pyPLUTO.pload object w\_dir -- /path/to/the/working/directory/ datatype -- If the data is of `float' type then datatype = `float' else by default the datatype is set to `double'. \end{quote} \emph{Required Keywords}: \begin{quote} plvar -- A string which represents the plot variable. \end{quote} \emph{Optional Keywords}: \begin{quote} logvar -- {[}Default = False{]} Set it True for plotting the log of a variable. rphi -- {[}Default = False - for plotting in r-theta plane{]} Set it True for plotting the variable in r-phi plane. \end{quote} \end{fulllineitems} \end{fulllineitems} \section{Additional tools} \label{tools:additional-tools}\label{tools::doc}\index{Tools (class in pyPLUTO)} \begin{fulllineitems} \phantomsection\label{tools:pyPLUTO.Tools}\pysigline{\strong{class }\code{pyPLUTO.}\bfcode{Tools}} This Class has all the functions doing basic mathematical operations to the vector or scalar fields. It is called after pyPLUTO.pload object is defined. \index{Div() (pyPLUTO.Tools method)} \begin{fulllineitems} \phantomsection\label{tools:pyPLUTO.Tools.Div}\pysiglinewithargsret{\bfcode{Div}}{\emph{u1}, \emph{u2}, \emph{x1}, \emph{x2}, \emph{dx1}, \emph{dx2}, \emph{geometry=None}}{} This method calculates the divergence of the 2D vector fields u1 and u2. \textbf{Inputs:} \begin{quote} u1 -- 2D vector along x1 whose divergence is to be determined. u2 -- 2D vector along x2 whose divergence is to be determined. x1 -- The `x' array x2 -- The `y' array dx1 -- The grid spacing in `x' direction. dx2 -- The grid spacing in `y' direction. geometry -- The keyword \emph{geometry} is by default set to `cartesian'. It can be set to either one of the following : \emph{cartesian}, \emph{cylindrical}, \emph{spherical} or \emph{polar}. To calculate the divergence of the vector fields, respective geometric corrections are taken into account based on the value of this keyword. \end{quote} \textbf{Outputs:} \begin{quote} A 2D array with same shape as u1(or u2) having the values of divergence. \end{quote} \end{fulllineitems} \index{Grad() (pyPLUTO.Tools method)} \begin{fulllineitems} \phantomsection\label{tools:pyPLUTO.Tools.Grad}\pysiglinewithargsret{\bfcode{Grad}}{\emph{phi}, \emph{x1}, \emph{x2}, \emph{dx1}, \emph{dx2}, \emph{polar=False}}{} This method calculates the gradient of the 2D scalar phi. \textbf{Inputs:} \begin{quote} phi -- 2D scalar whose gradient is to be determined. x1 -- The `x' array x2 -- The `y' array dx1 -- The grid spacing in `x' direction. dx2 -- The grid spacing in `y' direction. polar -- The keyword should be set to True inorder to estimate the Gradient in polar co-ordinates. By default it is set to False. \end{quote} \textbf{Outputs:} \begin{quote} This routine outputs a 3D array with shape = (len(x1),len(x2),2), such that {[}:,:,0{]} element corresponds to the gradient values of phi wrt to x1 and {[}:,:,1{]} are the gradient values of phi wrt to x2. \end{quote} \end{fulllineitems} \index{RTh2Cyl() (pyPLUTO.Tools method)} \begin{fulllineitems} \phantomsection\label{tools:pyPLUTO.Tools.RTh2Cyl}\pysiglinewithargsret{\bfcode{RTh2Cyl}}{\emph{R}, \emph{Th}, \emph{X1}, \emph{X2}}{} This method does the transformation from spherical coordinates to cylindrical ones. \textbf{Inputs:} \begin{quote} R - 2D array of spherical radius coordinates. Th - 2D array of spherical theta-angle coordinates. X1 - 2D array of radial component of given vector X2 - 2D array of thetoidal component of given vector \end{quote} \textbf{Outputs:} \begin{quote} This routine outputs two 2D arrays after transformation. \end{quote} \textbf{Usage:} \begin{quote} \code{import pyPLUTO as pp} \code{import numpy as np} \code{D = pp.pload(0)} \code{ppt=pp.Tools()} \code{TH,R=np.meshgrid(D.x2,D.x1)} \code{Br,Bz=ppt.RTh2Cyl(R,TH,D.bx1,D.bx2)} \end{quote} D.bx1 and D.bx2 should be vectors in spherical coordinates. After transformation (Br,Bz) corresponds to vector in cilindrical coordinates. \end{fulllineitems} \index{congrid() (pyPLUTO.Tools method)} \begin{fulllineitems} \phantomsection\label{tools:pyPLUTO.Tools.congrid}\pysiglinewithargsret{\bfcode{congrid}}{\emph{a}, \emph{newdims}, \emph{method='linear'}, \emph{centre=False}, \emph{minusone=False}}{} Arbitrary resampling of source array to new dimension sizes. Currently only supports maintaining the same number of dimensions. To use 1-D arrays, first promote them to shape (x,1). Uses the same parameters and creates the same co-ordinate lookup points as IDL''s congrid routine, which apparently originally came from a VAX/VMS routine of the same name. \textbf{Inputs:} \begin{quote} a -- The 2D array that needs resampling into new dimensions. newdims -- A tuple which represents the shape of the resampled data method -- This keyword decides the method used for interpolation. \begin{quote} neighbour - closest value from original data nearest and linear - uses n x 1-D interpolations using scipy.interpolate.interp1d (see Numerical Recipes for validity of use of n 1-D interpolations) spline - uses ndimage.map\_coordinates \end{quote} centre -- This keyword decides the positions of interpolation points. \begin{quote} True - interpolation points are at the centres of the bins False - points are at the front edge of the bin \end{quote} minusone -- This prevents extrapolation one element beyond bounds of input array \begin{quote} For example- inarray.shape = (i,j) \& new dimensions = (x,y) False - inarray is resampled by factors of (i/x) * (j/y) True - inarray is resampled by(i-1)/(x-1) * (j-1)/(y-1) \end{quote} \end{quote} \textbf{Outputs:} \begin{quote} A 2D array with resampled data having a shape corresponding to newdims. \end{quote} \end{fulllineitems} \index{deriv() (pyPLUTO.Tools method)} \begin{fulllineitems} \phantomsection\label{tools:pyPLUTO.Tools.deriv}\pysiglinewithargsret{\bfcode{deriv}}{\emph{Y}, \emph{X=None}}{} Calculates the derivative of Y with respect to X. \textbf{Inputs:} \begin{quote} Y : 1-D array to be differentiated. X : 1-D array with len(X) = len(Y). If X is not specified then by default X is chosen to be an equally spaced array having same number of elements as Y. \end{quote} \textbf{Outputs:} \begin{quote} This returns an 1-D array having the same no. of elements as Y (or X) and contains the values of dY/dX. \end{quote} \end{fulllineitems} \index{getUniformGrid() (pyPLUTO.Tools method)} \begin{fulllineitems} \phantomsection\label{tools:pyPLUTO.Tools.getUniformGrid}\pysiglinewithargsret{\bfcode{getUniformGrid}}{\emph{r}, \emph{th}, \emph{rho}, \emph{Nr}, \emph{Nth}}{} This method transforms data with non-uniform grid (stretched) to uniform. Useful for stretched grid calculations. \textbf{Inputs:} \begin{quote} r - 1D vector of X1 coordinate (could be any, e.g D.x1). th - 1D vector of X2 coordinate (could be any, e.g D.x2). rho- 2D array of data. Nr - new size of X1 vector. Nth- new size of X2 vector. \end{quote} \textbf{Outputs:} \begin{quote} This routine outputs 2D uniform array Nr x Nth dimension \end{quote} \textbf{Usage:} \begin{quote} \code{import pyPLUTO as pp} \code{import numpy as np} \code{D = pp.pload(0)} \code{ppt=pp.Tools()} \code{X1new, X2new, res = ppt.getUniformGrid(D.x1,D.x2,D.rho,20,30)} X1new - X1 interpolated grid len(X1new)=20 X2new - X2 interpolated grid len(X2new)=30 res - 2D array of interpolated variable \end{quote} \end{fulllineitems} \index{myInterpol() (pyPLUTO.Tools method)} \begin{fulllineitems} \phantomsection\label{tools:pyPLUTO.Tools.myInterpol}\pysiglinewithargsret{\bfcode{myInterpol}}{\emph{RR}, \emph{N}}{} This method interpolates (linear interpolation) vector 1D vector RR to 1D N-length vector. Useful for stretched grid calculations. \textbf{Inputs:} \begin{quote} RR - 1D array to interpolate. N - Number of grids to interpolate to. \end{quote} \textbf{Outputs:} \begin{quote} This routine outputs interpolated 1D array to the new grid (len=N). \end{quote} \textbf{Usage:} \begin{quote} \code{import pyPLUTO as pp} \code{import numpy as np} \code{D = pp.pload(0)} \code{ppt=pp.Tools()} \code{x=linspace(0,1,10) \#len(x)=10} \code{y=x*x} \code{Ri,Ni=ppt.myInterpol(y,100) \#len(Ri)=100} Ri - interpolated numbers; Ni - grid for Ri \end{quote} \end{fulllineitems} \index{sph2cyl() (pyPLUTO.Tools method)} \begin{fulllineitems} \phantomsection\label{tools:pyPLUTO.Tools.sph2cyl}\pysiglinewithargsret{\bfcode{sph2cyl}}{\emph{D}, \emph{Dx}, \emph{rphi=None}, \emph{theta0=None}}{} This method transforms spherical data into cylindrical applying interpolation. Works for stretched grid as well, transforms poloidal (R-Theta) data by default. Fix theta and set rphi=True to get (R-Phi) transformation. \textbf{Inputs:} \begin{quote} D - structure from `pload' method. Dx - variable to be transformed (D.rho for example). \end{quote} \textbf{Outputs:} \begin{quote} This routine outputs transformed (sph-\textgreater{}cyl) variable and grid. \end{quote} \textbf{Usage:} \begin{quote} \code{import pyPLUTO as pp} \code{import numpy as np} \code{D = pp.pload(0)} \code{ppt=pp.Tools()} \code{R,Z,res = ppt.sph2cyl(D,D.rho.transpose())} R - 2D array with cylindrical radius values Z - 2D array with cylindrical Z values res - 2D array of transformed variable \end{quote} \end{fulllineitems} \end{fulllineitems} \chapter{pyPLUTO Module.} \label{index:pypluto-module} The pyPLUTO module can be loaded as follows. \code{import pyPLUTO as pp} The functions associated with this module are listed below : \phantomsection\label{index:module-pyPLUTO}\index{pyPLUTO (module)}\index{get\_nstepstr() (in module pyPLUTO)} \begin{fulllineitems} \phantomsection\label{index:pyPLUTO.get_nstepstr}\pysiglinewithargsret{\code{pyPLUTO.}\bfcode{get\_nstepstr}}{\emph{ns}}{} Convert the float input \emph{ns} into a string that would match the data file name. \textbf{Inputs}: \begin{quote} ns -- Integer number that represents the time step number. E.g., The ns for data.0001.dbl is 1. \end{quote} \textbf{Outputs}: \begin{quote} Returns the string that would be used to complete the data file name. E.g., for data.0001.dbl, ns = 1 and pyPLUTO.get\_nstepstr(1) returns `0001' \end{quote} \end{fulllineitems} \index{nlast\_info() (in module pyPLUTO)} \begin{fulllineitems} \phantomsection\label{index:pyPLUTO.nlast_info}\pysiglinewithargsret{\code{pyPLUTO.}\bfcode{nlast\_info}}{\emph{w\_dir=None}, \emph{datatype=None}}{} Prints the information of the last step of the simulation as obtained from dbl.out or flt.out \textbf{Inputs}: \begin{quote} w\_dir -- path to the directory which has the dbl.out(or flt.out) and the data datatype -- If the data is of `float' type then datatype = `float' else by default the datatype is set to `double'. \end{quote} \textbf{Outputs}: \begin{quote} This function returns a dictionary with following keywords - nlast -- The ns for the last file saved. time -- The simulation time for the last file saved. dt -- The time step dt for the last file. Nstep -- The Nstep value for the last file saved. \end{quote} \textbf{Usage}: \begin{quote} In case the data is `float'. \code{wdir = /path/to/data/directory} \code{import pyPLUTO as pp} \code{A = pp.nlast\_info(w\_dir=wdir,datatype='float')} \end{quote} \end{fulllineitems} \chapter{Graphic User Interface} \label{index:graphic-user-interface} The Graphic User Interface for the pyPLUTO code. \begin{figure}[htbp] \centering \includegraphics{GetStarted.png} \end{figure} The Graphic User Interface of the pyPLUTO code for a typical three dimensional Hydrodynamical example. \textbf{Usage :} On installing the pyPLUTO source code via local install process, the executable for the GUI version of the code will be present in \code{\textless{}path to MyPython\_Modules\textgreater{}/bin}. In order to use directly from the command line append the \code{\$PATH} variable as follows: \code{export PATH=\textless{}path to MyPython\_Modules\textgreater{}/bin:\$PATH}, after which data can be visualized using following commands in the directory which has the relevant data - \code{GUI\_pyPLUTO.py} - This will work in case the data is in double format. \code{GUI\_pyPLUTO.py -{-}float} -- For data in float format one has to use the flag \emph{--float} The various functionalities in the Graphic User Interface (GUI) of the pyPLUTO code are marked with numbers as shown in the figure and explained in details below: 1. \textbf{Save As} : The drop down menu allows the user to save the figure displayed in various formats viz. `eps', `pdf', `jpg', `png'. \textbf{NOTE} - In case of surface images, it is recommended to save as `png' and/or `jpg' and then convert as the way the code plots surface is using pcolormesh (to account for non-uniform grid) and its been a known fact that rendering of pcolormesh images in eps takes loads of time. 2. \textbf{Quit} : The user can close the GUI using this button. 3. \textbf{Loading the Data} : This allows the user to load data. \begin{quote} a. \textbf{Nstep} : The number of the data file should be inputted in the blank panel provided. By default initial data file i.e. Nstep = 0 is loaded. The input number should be a valid positive number and the corresponding data file should exists in the working directory. b. \textbf{Load Data} : The user can click on this button to load the appropriate data file whose number is inputted in the Nstep panel. Each time the user modifies the value in the Nstep field, this button needs to be clicked to load the corresponding file. \end{quote} 4. \textbf{Axis cuts} : The user can choose the appropriate values in these panels to plot/image a particular cut/slice. No default value is set so error will occur if invalid entry is inputted. \begin{quote} a. \textbf{x1} : The field to input the x1 cut value. This field should not be blank if the user either chooses \emph{Along x2} or \emph{Along x3} or \emph{Along x2-x3} in (6). This field is disabled if the problem considered is 1-D. b. \textbf{x2} : The field to input the x2 cut value. This field should not be blank if the user either chooses \emph{Along x1} or \emph{Along x3} or \emph{Along x3-x1} in (6). This field is disabled if the problem considered is 1-D. c. \textbf{x3} : The field to input the x3 cut value. This field should not be blank if the user either chooses \emph{Along x1} or \emph{Along x2} or \emph{Along x1-x2} in (6). This field is disabled if the problem considered is either 1-D or 2-D. \end{quote} 5. \textbf{Choose Variables} : The user can choose the variable to plot from the list. This list also includes any additional variable stored using the \emph{userdef\_output.c}. So basically all the variables listed in the \emph{dbl.out} (or \emph{flt.out}) are enlisted in this column. The code will have a disabled \emph{Plot} and \emph{Surface}, until a variable is chosen in this column. \textbf{NOTE} - If the user wish to plot a userdef variable and also saves the vector potential then it is recommended to save data as multiple\_files instead of single\_file in pluto.ini. 6. \textbf{Choose Slices} : The code provides the user to either plot a 1D \emph{Plot} of any of the chosen variable along any axis. Alternatively, the code also allows the user to make a 2D \emph{Surface} image along any combination of two axes. This column is redundant in case the numerical problem under consideration is a 1D problem. With the choice of the slice, the user should also have appropriate axis cuts specified as mentioned above else the code will result into an error. 7. \textbf{Additional Processing} : The GUI interface allows the user to carry some additional processing on the variable chosen. They are the following - \begin{quote} a. \textbf{Log} : The user can plot logarithmic values using this option. b. \textbf{Polar} : The user can use this option to project the data from Spherical coordinates to Cylindrical coordinates. In the present version, the code handles the projection in the r-\(\theta\) plane (\emph{Along x1-x2}) and the r-\(\phi\) plane (\emph{Along x3-x1}). c. \textbf{Aspect} : Choosing this option allows the user to ensure that the image (only the Surface) produced has proper aspect ratio. By default the aspect ratio is set to `auto'. d. \textbf{Contour} : The user can choose this option to overplot the surface plot with contours {[}see (10 a,b){]}. e. \textbf{Arrow} : The user can choose this option to overplot the surface plot with vector arrows {[}see (11 a,b){]}. \end{quote} 8. \textbf{Information Panel} : The user can view the basic information regarding the problem under consideration. In this panel, the user can get information of the current working directory, along with the domain of the numerical problem and finally also the final time step of that problem. 9. \textbf{Figure Window} : In this panel the corresponding \emph{Plot} or the \emph{Surface} (image with colorbar) will be displayed. In order that the GUI fits into the whole screen, the user can play with the size of the figure by modifying the code and specifying the size of the figure window. The default value is : figsize=(7,7). 10. \textbf{Contours} : The user can activate this option by choosing the \emph{Contour} tab {[}7(d){]}. \begin{quote} a. \textbf{Contour Variable} : The 2D contours of listed variables can be plotted on the surface plot. The user can choose among all the variables that are available for plotting along with additional provision {[}only for the MHD problem{]} of plotting the \emph{Current} {[}x1*b3{]} and \emph{Magnetic field lines} {[}x1*A3{]}. The Magnetic field lines contour will only work if the code data consists information on the vector potential `A3'. The list by default is set to `None' and thus will give error is the user tries to plot contours without choosing the appropriate variable from the drop down list. b. \textbf{Contour Levels} : The user can provide the contours levels which is required separated by `,'. If the user does not wish to provide the levels then by default a total of 5 contours of automatically chosen levels will be displayed. Further, the user can also choose to display logarithmic contours by having the first entry in this panels as \emph{log}. For example, \begin{itemize} \item {} log,-1.5,-1.8,-2.0 : This plots the logarithmic contours for the chosen Contour variable at levels marked by 10\textasciicircum{}\{-1.5\}, 10\textasciicircum{}\{-1.8\} and 10\textasciicircum{}\{-2.0\} \item {} 1.0,2.0,3.0 : This will display normal contours for the chosen Contour variable at levels marked by 1.0, 2.0, and 3.0 \item {} Blank {[}Default{]}: 5 contours of automatically chosen levels will be displayed \end{itemize} There is no limit to the number of levels that can be inputed in this field. By convention all negative contours will be shown as \emph{dashes}. In case of logarithmic contours, the \emph{dashes} would represent contours for levels less than unity. \end{quote} 11. \textbf{Arrows} : The user can activate this option by choosing the `Arrows' tab {[}7(e){]}. \begin{quote} a. \textbf{Arrow Variable} : The vector arrows of velocity field {[}Vp and Vp\_norm{]} and the magnetic field {[}Bp and Bp\_norm{]} (only in MHD) can be displayed. The options of . The variables with `\_norm' indicate that the arrows are normalized, i.e. each arrow will have unit length. The list by default is set to `None' and thus will give error is the user tries to plot arrows without choosing the appropriate variable from the drop down list. b. \textbf{Arrow Spacing} : The user can provide the spacing value which indicates the size of the congrid matrix used to create the vector plots. Higher values will produce a more ``dense'' plot. Default is set to 20. \end{quote} 12. \textbf{Plot} : This button is by default deactivated and it will be active only when the user has fulfilled the conditions of valid loading of data {[}(3) a,b{]}, choosing the variable {[}(5){]} and choosing to plot either Along x1 or Along x2 or Along x3 {[}(6){]}. Only in case of 1-D numerical problems this button will be activated by default. 13. \textbf{Surface} : This button is by default deactivated and it will be active only when the user has fulfilled the conditions of valid loading of data {[}(3) a,b{]}, choosing the variable {[}(5){]} and choosing to plot either \emph{Along x1-x2} or \emph{Along x2-x3} or \emph{Along x3-x1} {[}(6){]}. Consecutively pressing this button will clear the existing image and create a new one. 14. \textbf{Clear} : This button allows the user to clear the plot. 15. \textbf{Labels} : The user can choose the x and y labels for their plots/images. The user can also use standard TeX symbols within the `\$' sign. By default they are set to `xlabel' and `ylabel' respectively. 16. \textbf{Ranges} : The user can choose range of values to be displayed from these panels. \begin{quote} a. \textbf{Xrange} : To set the minimum (left entry) and maximum (right entry) range of the X axis. A `blank' entry would mean that by default the minimum and the maximum of the X vector will be shown (i.e. the full range). b. \textbf{Yrange} : To set the minimum (left entry) and maximum (right entry) range of the Y axis. A `blank' entry would mean that by default the minimum and the maximum of the Y vector will be shown (i.e. the full range). This becomes ineffective in case if the user wants to plots a line. To set the range for the Y axis in case of `Plot', the user should use the VarRange option. c. \textbf{VarRange} : To set the minimum (left entry) and maximum (right entry) range of the Variable. A `blank' entry would mean that by default the minimum and the maximum of the Variable will be shown (i.e. the full range). In case the user wants a `Surface' image then with this option the user can choose the maximum and the minimum of the image. In case of `Plot', this becomes the Y axis range. \end{quote} \chapter{Indices and tables} \label{index:indices-and-tables}\begin{itemize} \item {} \emph{genindex} \item {} \emph{search} \end{itemize} \renewcommand{\indexname}{Python Module Index} \begin{theindex} \def\bigletter#1{{\Large\sffamily#1}\nopagebreak\vspace{1mm}} \bigletter{p} \item {\texttt{pyPLUTO}}, \pageref{index:module-pyPLUTO} \end{theindex} \renewcommand{\indexname}{Index} \printindex \end{document}