******************
Usage of Pyflation
******************

Basic usage of the pyflation package
====================================

The pyflation package can be used independently of the scripts which run full
first and second order calculations. If you have installed the package using
the setup.py install command then it should be available by doing

    > import pyflation

in an interactive Python session. If you have not installed the package then 
make sure that the path where the pyflation directory is located has been 
added to the PYTHONPATH variable.

The most important module in the package is cosmomodels. This contains the 
classes which drive first and second order evolution. To run a first order
simulation with the default settings first import the cosmomodels module:

    > from pyflation import cosmomodels as c

Here the module is aliased as c for convenience. Then create a new first order
model using the FOCanonicalTwoStage class:

    > m = c.FOCanonicalTwoStage()

You can inspect the attributes and methods of m in the usual way by using 
dir(m) or tab completion in the iPython environment.

To begin the first order run use:

    > m.run()

The results are stored in m.yresult in raw form for all time steps. 
The value of the first order perturbations for all time steps are also labelled 
as m.dp1.  

Basic Usage of Scripts
======================

Assuming you have followed the instructions in INSTALL.txt to install the program
either system-wide, locally, or in a contained directory, you can create a new
run directory using the pyflation-newrun.py script.

If you have used the setup.py install command, the script should be somewhere
on your PATH. If not you will need to prefix the following commands with the 
path to the pyflation-newrun.py script.
To create a new run in the directory $HOME/pyflation-runs and call the run
mynewrun run the pyflation-newrun.py script with the following options:

    $ pyflation-newrun.py -d $HOME/pyflation-runs -n mynewrun

The script should create the directory (and any parent ones needed) and set up 
the file structure inside. Change to the run directory and look inside. The 
directories applogs, qsublogs, qsubscripts and results are created automatically 
and the run_config.py file is put inside the run directory. If you want the code 
to be copied in to the run directory please see the advanced options of the 
pyflation-newrun.py script.

The run_config.py file inside the run directory contains user changeable settings.
In particular the choice of potential and k range to be used in the scripts is
made here. The python classes used for the different stages of the evolution
can also be changed in this file.

The script files are descriptively named. To begin a first order perturbation
calculation use pyflation-firstorder.py. For each script the --help option will
show all the options available. Simple operation uses the defaults in 
run_config.py for example

    $ pyflation-firstorder.py

will run the first order code and store the result in the file specified in 
run_config.py, usually results/fo.hf5. 

Description of available scripts
================================

* The pyflation-newrun.py script creates a new run directory and the needed
  directories and files inside it. Options include the ability to copy the 
  code into the new run directory to keep it contained.

* The pyflation-firstorder.py script runs background and first order perturbation
  simulations and saves the results, by default in results/fo.hf5.

* The pyflation-source.py script runs a full source term calculation using the
  first order results. This may take a long time especially if it is not executed
  in parallel. The options for this script include the location of the first
  order results file and simple assignment of task number in a parallel (or multiple
  serial) environment.

* The pyflation-srcmerge.py script will merge any separate source files, for 
  example from a parallel run, into one main source file. Rudimentary checking
  of the existence of each time step is completed. One of the options to this 
  script is to further merge the first order and source term results together.
  The new merged file is used as the input for the second order calculation.

* The pyflation-secondorder.py script uses the source term and first order
  results from the merged file to calculate the second order perturbation solution.

* The pyflation-combine.py script combines all the results from the first, 
  source and second order runs into one final results file. In this file the
  timesteps from the second order run are used so only half the results of the 
  first and source term calculations are stored. For this reason this file is more 
  for ease of analysis then long term data storage.

* The pyflation-qsubstart.py script is used when the qsub queueing command is
  available. See the section "Using Qsub" below for more information. 

Using Qsub 
==========

If you are running Pyflation in a cluster environment or somewhere with the
qsub queueing system available, there is an extra pyflation-qsubstart.py script
which will be useful. When you create a new run the file qsub-sh.template is 
created which holds a very general outline of a qsub run script. Change any 
of the options in the preliminary section to meet your needs. The length of runs
and the number of task units can be set in run_config.py.
When you run

    $ pyflation-qsubstart.py

a new batch of qsub jobs will be created and submitted, running a full second
order calculation. Please note that the full calculation make take some 
considerable time depending on the available computing power. The scripts which
are submitted using qsub are available in the directory qsub-scripts. An 
additional src_individual.qsub script is useful if one of the tasks in the long
source term calculation fails for some reason. To restart just one task with
the same options as before use

    $ qsub src_individual.qsub N

where N is the number of the task to restart.
