pencil.diag.particle
====================

.. py:module:: pencil.diag.particle

.. autoapi-nested-parse::

   Diagnostics for particles.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /code/sourcePython/pencil/diag/particle/diffusion/index
   /code/sourcePython/pencil/diag/particle/dispersion_and_drift/index
   /code/sourcePython/pencil/diag/particle/gas_velco_at_particle_pos/index
   /code/sourcePython/pencil/diag/particle/gas_velo_at_particle_pos/index


Classes
-------

.. autoapisummary::

   pencil.diag.particle.DiffusionData


Functions
---------

.. autoapisummary::

   pencil.diag.particle.diffusion
   pencil.diag.particle.dispersion_and_drift
   pencil.diag.particle.gas_velo_at_particle_pos


Package Contents
----------------

.. py:function:: diffusion(directions=['x'], trange=[0, -1], sim='.', OVERWRITE=False, quiet=True, jump_distance=0.5, use_existing_pstalk_sav=False)

   Calculate particle diffusion via stalked particles: PSTALK
   Therefore, it read PSTALK files from Pencil Code using IDL by
   using the IDL<->Python Bridge. It may be activated manually!

   Generated DiffusionData object will be stored in:
       sim.pc_datadir/particle/diffusion/<direction>_<t_start>:<t_end>
   and be reloaded and returned if already existing and OVERWRITE=False!

   :param - sim: simulation object, but also simulations object or
                 list of simulations or path of simulation,
                  default ='.'
   :param - directions   list or directions to calculate diffusion for: default =['x']
   :param e.g. ['x': default =['x']
   :param 'y': default =['x']
   :param 'z']: default =['x']
   :param : default =['x']
   :param - trange       range in code time for which diffusion shall be calc.: default =[0, -1]
   :param - jump_distance expressed in L_: half the domain size
   :type - jump_distance expressed in L_: x,y,z
   :param - OVERWRITE    previously calculated diffusions shall be overwritten: default =False
   :param - quiet        verbosity:
   :param default =False:
   :param - use_existing_pstalk_sav: use existing <sim.datadir>/data/pc/tmp/pstalk.sav for speed up

   :returns: diffusion object for simulation,
             if function is called for a set of simulations, a dictionary with all
             diffusion objects and simulation-name as key is returned


.. py:class:: DiffusionData(direction='x', trange=[0, -1], sim='.', OVERWRITE=False, quiet=True, jump_distance=0.5, use_existing_pstalk_sav=False)

   Bases: :py:obj:`object`


   DiffusionData -- holds diffusion data for particles.


.. py:function:: dispersion_and_drift(sim=False, OVERWRITE=False, GLOBAL=True, LOCAL=True, use_IDL=False, recalculate_gas_velo_at_particle_pos=False)

   This calculates the dispersion (sigma) and drift (zeta) locally and globally
   by using the gas_velo_at_particle_pos script and dataset for all particles.

   With sigma = sqrt( 1/N_par * sum_i^N_par( (v_par(i) - <v_par>)^2 ) ) and
   zeta = sqrt( 1/N_par * sum_i^N_par( (v_par(i) - u(xp_i))^2 ) )

   Arg:
         OVERWRITE:            set to True to overwrite already calculated results
     GLOBAL:         Calculate drift and dispersion globally, i.e. whole simulation domain
     LOCAL:          Calculate drift and dispersion locally, i.e. grid cell wise
     recalculate_gas_velo_at_particle_pos:
                   if the dataset shall be recalcualted
     use_IDL:  use backup solution of IDL script and sav files

     returns True if successfull


.. py:function:: gas_velo_at_particle_pos(varfiles='last4', sim=False, scheme='tsc', use_IDL=False, OVERWRITE=False)

   This script calulates the gas velocity at the particle position and stores this together
   with particle position, containing grid cell idicies, particle velocities, and particle index
   in a gas_velo_at_particle_pos file.

   :param varfiles: specifiy varfiles for calculation, e.g. 'last', 'first',
                    'all', 'VAR###', 'last4', 'first3'
   :param scheme: possible are:
                  - ngp: nearest grid point
                  - cic: cloud in cell
                  - tsc: triangular shaped cloud
   :param OVERWRITE: set to True to overwrite already calculated results