.. Piernik MHD code documentation master file, created by
   sphinx-quickstart on Mon Aug  4 13:00:52 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Composing the code
==============================================
The code uses precompiler directives. All of them are supposed to be set in the file piernik.def in the problem directory.

Precompiler directives:

* are used to select parts of PIERNIK code, which are relevant for given problem
* instruct setup on which routines should be selected for compilation in ./obj directory
* instruct precompiler on which parts of selected routines should be retained for compilation




FLUID COMPONENTS:
~~~~~~~~~~~~~~~~~

.. _def_ionized:

   ``#define`` **IONIZED**
         to include parts of the code related to ionized fluid

.. _def_neutral:

   ``#define`` **NEUTRAL**
         to include parts of the code related to neutral fluid

.. _def_dust:

   ``#define`` **DUST**
         to include parts of the code related to dust fluid

.. _def_cosm_rays:

   ``#define`` **COSM_RAYS**
         to include parts of the code related to cosmic ray component

.. _def_cosm_rays_sources:

   ``#define`` **COSM_RAYS_SOURCES**
         to take into account several different species of cosmic rays particles

.. _def_tracer:

   ``#define`` **TRACER**
         to include parts of the code related to tracer



PHYSICS INCLUDED (i.e. FIELDS, INTERACTIONS):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _def_iso:

   ``#define`` **ISO**
         the choice between adiabatic and isothermal fluids (if defined then isothermal fluid is set, otherwise adiabatic)

.. _def_iso_local:

   ``#define`` **ISO_LOCAL**
         to choose isothermal fluids with locally specified soundspeed and temperature (required :ref:`ISO <def_iso>`; currently works only with :ref:`IONIZED <def_ionized>` fluid.)

.. _def_magnetic:

   ``#define`` **MAGNETIC**
         to include parts of the code related to magnetic field (otherwise magnetic field is switched off even if ionized fluid is simulated)

.. _def_resistive:

   ``#define`` **RESISTIVE**
         to include resistive dissipation of magnetic field

.. _def_fluid_interactions:

   ``#define`` **FLUID_INTERACTIONS**
         to take into account interactions between different fluids (eg. drag force)

.. _def_balsara:

   ``#define`` **BALSARA**
         switch to implicit scheme for interactions from `Balsara et al. MNRAS (2009) 397 24 <http://cdsads.u-strasbg.fr/abs/2009MNRAS.397...24B>`_ and `Tilley & Balsara MNRAS (2008) 389 1058 <http://cdsads.u-strasbg.fr/abs/2008MNRAS.389.1058T>`_

.. _def_grav:

   ``#define`` **GRAV**
      to include gravitational forces. The type of gravity is govern by :ref:`external_gp <nml_gravity>` value. Then chosen gravitational potential is computed. If no gravity type is defined by external_gp character value then grav_accel defined by user is used and from given gravitational acceleration potential is computed.

.. _def_variable_user_gp:

   ``#define`` **VARIABLE_USER_GP**
         user flag to switch on gravity maxima dumps to log and tsl files (for :ref:`SELF_GRAV <def_self_grav>` this is as default)

.. _def_coriolis:

   ``#define`` **CORIOLIS**
         switch on Coriolis force (works only with :ref:`RTVD <def_rtvd>` scheme.)

.. _def_sn_src:

   ``#define`` **SN_SRC**
         switch on supernovae insert: supernovae initialization is called and random_sn routine is available to be hooked e.g. to :ref:`problem_customize_solution <newprobl_pcustsol>`


NUMERICAL SCHEMES AND SOLUTIONS:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _def_rtvd:

   ``#define`` **RTVD**
         to choose Relaxing TVD scheme (then :ref:`HLLC <def_hllc>` cannot be defined). Set by default if no scheme is chosen.

.. _def_hllc:

   ``#define`` **HLLC**
         to choose HLLC scheme (without magnetic fields; :ref:`RTVD <def_rtvd>` cannot be defined)

.. _def_local_fr_speed:

   ``#define`` **LOCAL_FR_SPEED**
         choose locally computed freezing speed (i.e. in each cell) (then :ref:`GLOBAL_FR_SPEED <def_global_fr_speed>` cannot be defined)

.. _def_global_fr_speed:

   ``#define`` **GLOBAL_FR_SPEED**
         choose globally computed freezing speed (i.e. constant for the whole domain) (then :ref:`LOCAL_FR_SPEED <def_local_fr_speed>` cannot be defined)

.. _def_multigrid:

   ``#define`` **MULTIGRID**
         multigrid solver to include self–gravity (uses FFT when possible, recommended). Desired to be set with :ref:`GRAV <def_grav>` and/or :ref:`COSM_RAYS <def_cosm_rays>` flags.

.. _def_fftw:

   ``#define`` **FFTW**
         using *shear_fftw* (:ref:`SHEAR <def_shear>` should be defined)

.. _def_shear:

   ``#define`` **SHEAR**
         to include Coriolis and tidal forces in gas equation of motion and use `Hawley, Gammie and Balbus (1995) <http://cdsads.u-strasbg.fr/abs/1995ApJ...440..742H>`_ type approach for shearing BCS (only with :ref:`RTVD <def_rtvd>` scheme.)

.. _def_shear_bnd:

   ``#define`` **SHEAR_BND**
         shear boundary conditions.

.. _def_hydrostatic_v2:

   ``#define`` **HYDROSTATIC_V2**
         change hydrostatic_zeq scheme and find midplane corresponding to zero gravity (practically the least gravity absolute value)

.. _def_zero_bnd_emf:

   ``#define`` **ZERO_BND_EMF**
         switch to putting 0 on emf boundaries for outflow type boundary conditions instead of constant emf gradient as default

DIRECTIVES ALLOCATED TO PROBLEMS:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _def_jeans_problem:

   ``#define`` **JEANS_PROBLEM**
         switch on jeans problem-specific quirks

.. _def_maclaurin_problem:

   ``#define`` **MACLAURIN_PROBLEM**
         switch on maclaurin problem-specific quirks

.. _def_user_rules:

   ``#define`` **USER_RULES**
         include precompiler instructions from *user_rules.h* file from problem directory at the beginning of compilation


OTHERS:
~~~~~~~

.. _def_debug:

   ``#define`` **DEBUG**
         enable modules: piernikdebug (src/base/debug.F90) and piernikiodebug (src/hdf5/io_debug.F90)

.. _def_debug_dumps:

   ``#define`` **DEBUG_DUMPS**
         switch on HDF5 control dumps to debug refinement updates

.. _def_heavy_debug:

   ``#define`` **HEAVY_DEBUG**
         marks routines that normally are never called, but at some point were useful to test correctness or something.

.. _def_verbose:

   ``#define`` **VERBOSE**
         print additional diagnostic information on stdout

.. _def_independent_atoutb:

   ``#define`` **INDEPENDENT_ATOUTB**
         switch to independent (instead of collective) write to files (restart files) for arrays with outer boundary area type

.. _def_perfmon:

   ``#define`` **PERFMON**
         switch on counting total wallclock and cpu times and printing them at the end of a simulation.

.. _def_piernik_opencl:

   ``#define`` **PIERNIK_OPENCL**
         Include module responsible for integration of OpenCL in Piernik

.. _def___intel_compiler:

   ``#define`` **__INTEL_COMPILER**
         automatic flag placed by Intel Compiler

.. _def___pgi:

   ``#define`` **__PGI**
         flag for Portland Compilers


AUTOMATICALLY DEFINED:
~~~~~~~~~~~~~~~~~~~~~~

.. _def_self_grav:

   ``#define`` **SELF_GRAV**
         switch on self-gravity, automatically defined when :ref:`MULTIGRID <def_multigrid>` and :ref:`GRAV <def_grav>` are defined.

.. _def_variable_gp:

   ``#define`` **VARIABLE_GP**
         automatically defined when :ref:`SELF_GRAV <def_self_grav>` or :ref:`VARIABLE_USER_GP <def_variable_user_gp>` is defined.


INTERNAL (NOT ALLOWED TO USE BY USER!!!):
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _def_poisson_fft:

   ``#define`` **POISSON_FFT**
         Out-of-date. Flag to include self–gravity (pure FFT solver)

.. _def_hdf5:

   ``#define`` **HDF5**
         hdf5

.. _def_sn_galaxy:

   ``#define`` **SN_GALAXY**
         sn_galaxy

.. _def_magnetized:

   ``#define`` **MAGNETIZED**
         magnetized

.. _def_crs_galaxy:

   ``#define`` **CRS_GALAXY**
         crs_galaxy

.. _def_cr_sn:

   ``#define`` **CR_SN**
         cr_sn

.. _def_umuscl:

   ``#define`` **UMUSCL**
         umuscl

.. _def___gfortran__:

   ``#define`` **__GFORTRAN__**
         __gfortran__

.. _def_fr_speed:

   ``#define`` **FR_SPEED**
         Flag used to code configuration sanity checks. Do not define it!

.. _def_fr_speed2:

   ``#define`` **FR_SPEED2**
         Flag used to code configuration sanity checks. Do not define it!

.. _def_fluid:

   ``#define`` **FLUID**
         Flag used to code configuration sanity checks. Do not define it!

.. _def_hydro_solver:

   ``#define`` **HYDRO_SOLVER**
         Flag used to code configuration sanity checks. Do not define it!

.. _def_i_know_what_i_am_doing:

   ``#define`` **I_KNOW_WHAT_I_AM_DOING**
         i_know_what_i_am_doing

.. _def__crayftn:

   ``#define`` **_CRAYFTN**
         _crayftn

.. _def___test:

   ``#define`` **__TEST**
         __test

.. _def_psm:

   ``#define`` **PSM**
         Out-of-date. Use run-time parameter units_set from :ref:`UNITS <nml_units>` namelist instead of { PGM SSY SI CGS WT4 PSM PLN KSG KSM } preprocessor symbols.

.. _def_pln:

   ``#define`` **PLN**
         Out-of-date. Use run-time parameter units_set from :ref:`UNITS <nml_units>` namelist instead of { PGM SSY SI CGS WT4 PSM PLN KSG KSM } preprocessor symbols.

.. _def_ksg:

   ``#define`` **KSG**
         Out-of-date. Use run-time parameter units_set from :ref:`UNITS <nml_units>` namelist instead of { PGM SSY SI CGS WT4 PSM PLN KSG KSM } preprocessor symbols.

.. _def_ksm:

   ``#define`` **KSM**
         Out-of-date. Use run-time parameter units_set from :ref:`UNITS <nml_units>` namelist instead of { PGM SSY SI CGS WT4 PSM PLN KSG KSM } preprocessor symbols.

.. _def_pgm:

   ``#define`` **PGM**
         Out-of-date. Use run-time parameter units_set from :ref:`UNITS <nml_units>` namelist instead of { PGM SSY SI CGS WT4 PSM PLN KSG KSM } preprocessor symbols.

.. _def_ssy:

   ``#define`` **SSY**
         Out-of-date. Use run-time parameter units_set from :ref:`UNITS <nml_units>` namelist instead of { PGM SSY SI CGS WT4 PSM PLN KSG KSM } preprocessor symbols.

.. _def_si:

   ``#define`` **SI**
         Out-of-date. Use run-time parameter units_set from :ref:`UNITS <nml_units>` namelist instead of { PGM SSY SI CGS WT4 PSM PLN KSG KSM } preprocessor symbols.

.. _def_cgs:

   ``#define`` **CGS**
         Out-of-date. Use run-time parameter units_set from :ref:`UNITS <nml_units>` namelist instead of { PGM SSY SI CGS WT4 PSM PLN KSG KSM } preprocessor symbols.

.. _def_wt4:

   ``#define`` **WT4**
         Out-of-date. Use run-time parameter units_set from :ref:`UNITS <nml_units>` namelist instead of { PGM SSY SI CGS WT4 PSM PLN KSG KSM } preprocessor symbols.