$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.