___                     _  _      __                 
       / _ \  ___  _ __    ___ (_)| |  /\ \ \  ___ __      __
      / /_)/ / _ \| '_ \  / __|| || | /  \/ / / _ \\ \ /\ / /
     / ___/ |  __/| | | || (__ | || |/ /\  / |  __/ \ V  V / 
     \/      \___||_| |_| \___||_||_|\_\ \/   \___|  \_/\_/  


#############################
## DESCRIPTION
##
This python package contains a set of subroutines for postprocessing your Pencil Code data.
PencilNew will do all imports and diagnostics on your pencil code data in the best and easiest way possible. Therefore pen will store all calcuated data in separate files and reload if necessary.

#############################
## EASY START
##
1. Add $PENCIL_HOME/python to your $PYTHONPATH or enshure this is already done by using 'echo $PYTHONPATH' in your bash shell.

2. Start Python (or better ipython) from your simulation main folder (where the data directory is located) and try:
  import pencilnew as pcn

3. Try to read your time series:

  ts = pcn.read.ts()

this reads in the time_series.dat with all its data. Check out whats available:
  
  ts.keys

4. Try to read in the latest var.dat file:

  var = pcn.read.var()
  
  Check out whats available again with:
  
  var.keys

  var should have stored the whole latest f array snapshot from the var.dat file. 
  
5. Try to read in an earlier snapshot. First check which snapshots are available by getting you simulation as an object

  sim = pcn.get_sim()
  
6. Get the varlist:

  vars = sim.get_varlist()
  print(vars)
  
  then read the second snapshot:
  
  var_2nd = pcn.read.var(varfile=vars[1])
 
Now you can do investigate further your data.
  
Note that because python is C-indexed instead of fortran-indexed, and
matplotlib assumes [y,x] ordering for 2D plotting, the f array returned is in
the opposite order from how it is in pencil: var.f.shape will return
(nvar,nz,ny,nx).

#############################
## WHAT IS WHERE?
##

~ io           input und output functions, like save data or call IDL scripts
~ diag         diagnostic scripts and functions that produce physical meaningfull output
~ visu         visualization routines, here you find also helpers for e.g. exporting figures
~ calc         complex math functions and further calculations and helpers
~ math         basic math functions, like products and derivatives, but also numerical helpers, like is_number
~ sim          handling simulations as python objects and do stuff with simulations objects, like grouping and sorting
~ read         read data and parameters from your pencil code simulation, many of these functions can be accessed directly from simulation objects
~ tool_kit     all nice workarounds get stored here (e.g., resubmit script), but your dirty tools here!
~ export       exporter (e.g., vtk, xml)
~ backpack     third party modules, tribute goes to the authors!