news	institute	info	people	research	programs	meetings	computing

Pencil-Code

The purpose of these pages is to provide documentation that is either already in the manual, or new material that is better dealt with in the wiki format. Its advantage is that the multitude of Pencil Code users can more easily contribute to changes and enhancements. Some of the content may later be moved or copied into the manual.

Long term strategy for the CVS repository

During the Code User Meeting in 2008 it was decided that we shall move from CVS to subversion (SVN). It is in practice rather similar to CVS and has some advantages: links, renaming, and unique version numbers for the entire repository, so it is easier to track down the order of changes that were done. A temporary version of the SVN repository is available under https://norlx01.albanova.se/svn/pencil-code/. This system also comes with its own wiki with its own bug tracker; see https://norlx01.nordita.org/trac. Trac is now our reference bug tracker and incorporates previous entries that were done under bugzilla. However, while SVN is working, its content will later, at a moment still to be decided, be overwritten with whatever the state under CVS is, and CVS will then be closed.

Instructions for specific computers

fe03.esc.qmul.ac.uk

put the file ~brandenb/.adapt-mkfile.incl into your home directory.

Coding techniques

The mscratch feature

For certain applications one may want to use additional fully 3-dimensional work arrays (scratch space). Using a lot of additional work space was not in the original spirit of the Pencil Code, but using 3-dimensional work arrays gives much more freedom and sometimes speed advantages. The use of 3-dimensional work arrays is optional, so one never loses the advantage of low memory usage in the basic usage of the Pencil Code. Further details are discussed in the manual in Section 8.3 (II. Programming the Pencil Code -- Adapting the Code -- The f array).

Debugging techniques

Writing out pencil variables

Internal pencil variables (in particular all slots of the pencil structure p) only live on one pencil at a time, which implies that we cannot straight-forwardly write them to a file for external analysis or visualization.

This is where output_pencil() comes to the rescue, which works pretty much like output(), but takes the arguments

  output_pencil(file, pvar, ndim)

with pvar representing a (ndim-dimensional) pencil variable.

Currently the file format written by output_pencil() is slightly different from the one used by the snapshots var.dat, etc. To read the files into IDL, use the routine pc_read_penciled.pro.

Debug arrays

Additional scratch space can be allocated dynamically, but one needs to set MAUX CONTRIBUTION in cparam.local before any other instruction lines. An example are bb and jj output (look in magnetic.f90)

Compilers

g95

g95 passes the complete Pencil Code test suite. It is available for many platforms and has very good diagnostic capabilities.

To download g95 for Linux, proceed as follows:

1. Make sure you have a directory ~/bin that is in your path:
   
mkdir -p ~/bin
echo "PATH=${PATH}:${HOME}/bin" >> ~/.profile
echo "PATH=${PATH}:${HOME}/bin" >> ~/.bashrc
. ~/.profile

   
2. Get and unpack g95:
   
download='~/opt/lib/g95' # (or wherever you want to keep the g95 directory)
arch='x86-linux'         # (or arch='x86_64-32-linux' for a 64-bit system)
mkdir -p ${download}
cd ${download}
wget -O - http://ftp.g95.org/g95-${arch}.tgz | tar xvfz -

   
3. Create symbolic link to ~bin/ directory:
   

     ln -s ${download}/g95-install/bin/*-g95 ~/bin/g95

   
   

After this, you can use the compiler as `g95':

  g95 file.f90
  make FC='g95 -fno-second-underscore'

gfortran

Recent versions (>= 4.1.2) of gfortran pass most of the Pencil Code test suite. This compiler is supposed to produce fast code and it is part of the GCC compiler suite.

To compile the Pencil Code with gfortran, use the following gfortran-specific flags

  FC=gfortran -I/usr/include -I. -frecord-marker=4
  F77=$(FC)
  FFLAGS_SLOPPY=
  FFLAGS=-O3
  F90FLAGS=
  F77FLAGS=
  FFLAGS_DOUBLE=-fdefault-real-8
  CC=gcc
  CFLAGS=-O3 -DFUNDERSC=1

(put them in Makefile.src, or in ~/.adapt-mkfile). You may need some more flags to adjust for your specific MPI installation, etc.

Switching between compilers

If you tend to switch a lot between different compilers, you can write configuration settings for compiler XXX to ~/.adapt-mkfile_XXX.incl, for compiler YYY to ~/.adapt-mkfile_YYY.incl, etc.

Then you can compile using compiler YYY with

  make cleanall ADAPT_MKFILE=~/.adapt-mkfile_YYY.incl
  make

One can even set up different .incl files for different compiler options, e.g. optimization options, but it is often easier to switch those like this:

  make FFLAGS='-O0 -g'

Data analysis

Problems with time series file

Here is one of Wolfgang's tricks to deal with spurious extra dots in the time series file:

  perl -i.bak -pe 's/^(\s*[0-9]+)\./$1 /' data/time_series.dat

Links

The Pencil Code is now mentioned in the astro-sim webpage; see http://astro-sim.org/