$Id: README 10596 2009-04-19 20:32:49Z AxelBrandenburg $

This directory contains a sample of "initial condition" files that deal with
custom initial conditions. It allows a user to implement his/her initial 
condition, without overload for other users. 

The best way to start a new initial condition module is to go to 
pencil-code/src/ and copy noinitial_condition.f90 to 
initial_condition/NewInitialCondition.f90 and start editing
NewInitialCondition.f90 for your purposes. This approach is better 
than modifying an existing initial condition file, because they tend 
to be too specialized! The noinitial_condition.f90 module also contains 
lots of comments.

Example:
  cp noinitial_condition.f90 initial_condition/star_in_a_box.f90

However, looking for example also at initial_condition/mhs_equilibrium.f90 
might indeed be a good idea. 

The initial condition module consists of a set of standard hooks into the 
Pencil Code, and currently allows the following customizations:


   Description                               | Relevant function call
  ------------------------------------------------------------------------
   Initial condition registration            | register_special
     (pre parameter read)                    |
   Initial condition initialization          | initialize_special
     (post parameter read)                   |
                                             |
   Initial condition for momentum            | initial_condition_uu
   Initial condition for density             | initial_condition_lnrho
   Initial condition for entropy             | initial_condition_ss
   Initial condition for magnetic potential  | initial_condition_aa

And a similar subroutine for each module with an "init_XXX" call. 
The subroutines are organized IN THE SAME ORDER THAT THEY ARE CALLED. 
First uu, then lnrho, then ss, then aa, and so on.  

Save the file with a meaningful name, e.g. mhs_equilibrium.f90, and
place it in the $PENCIL_HOME/src/initial_condition directory. This
path has been created to allow users to optionally check their
contributions in to the Pencil Code SVN repository. This may be
useful if you are working on/using an initial condition with
somebody else or may require some assistance from one from the main
Pencil Code team. HOWEVER, less general initial conditions should
not go here (see below).

You can also place initial condition files directly in the run
directory. Simply create the folder 'initial_condition' at the same
level as the *.in files and place an initial condition file there.
With pc_setupsrc this file is linked automatically into the local
src directory. This is the preferred method for initial conditions
that are not very general.

To use your additional initial condition code, edit the
Makefile.local in the src directory under the run directory in which
you wish to use your initial condition. Add a line that says e.g.

    INITIAL_CONDITION =   initial_condition/mhs_equilibrium

Here mhs_equilibrium is replaced by the filename of your new file,
not including the .f90 extension.

This module is based on Tony's special module.

-----------------------------------------------------------------------------
List of initial conditions (31 July 2016)

Initial flux tube configurations:
  1D_loop_init.f90
  alfven_wave.f90
  borromean_rings.f90
  braids.f90
  fieldloop.f90
  fluxring_cylindrical.f90
  fluxrings.f90
  iucaa_logo.f90
  multi_rings.f90
  nfoil.f90
  trefoil.f90
  twistedtiltedtoros.f90
  twisted_tubes.f90
  whitehead_link.f90

Magnetic buoyancy and magnetostatic equilibria:
  hor-fluxlayer-By.f90
  mhs_equilibrium.f90

Initial flows:
  hill_vortex.f90
  aerosol_init.f90
  baroclinic_init.f90
  blobs_domes.f90
  bubbles_init.f90
  centrifugal_balance.f90
  centrifugal_balance_neutrals.f90

Benchmarks:
  cig_dynamo_benchmark.f90
  kelvin_helmholtz.f90
  kelvin_helmholtz_Lecoanet_etal16.f90
  Orszag_Tang_Vortex.f90
  Rayleigh-Taylor.f90
  rti.f90
  shocktube.f90

Accretion disks & MRI:
  circumplanetary.f90
  dust-equilibrium.f90
  ice_shell.f90
  cylindrical_energy.f90
  MRI_2D_Test.f90
  mri_cycle.f90
  mri_nonlinear.f90
  viscous_ring.f90

Solar:
  coronae_init.f90
  magnetic_carpet.f90
  parker_wind.f90

ISM:
  hs_equilibrium_ism.f90
  ths1D_equilibrium_ism.f90
  ths_equilibrium_ism.f90

Convection:
  spherical_convection.f90
  star_box_layers.f90

Other:
  assimilate.f90
  hydrostat-pload.f90
  import_glemur.f90
  random_helical.f90
  reflect.f90
  shock_cloud.f90
  tabulated.f90
  wave_Bx.f90

Comments:
  AB: a reference to an example would be useful (e.g. in the samples)
  AB: clarify role of rti vs Rayleigh-Taylor