PyBoxLib
========

PyBoxLib is a Python wrapper of the C++ version of `BoxLib`_.

An alternative version that wraps the Fortran version of `BoxLib`_ is
available in the 'F90' directory.


.. _`BoxLib`: https://ccse.lbl.gov/BoxLib/index.html


Install
=======

$ python setup.py build
$ python setup.py install

Compiling options
-----------------

To compile PyBoxLib without MPI support, build using:

$ python setup.py build --disable-mpi

If you are building with MPI support, the MPI compilers wrapper
'mpicc' and 'mpic++' should be in your PATH.  If not, you can set the
MPIHOME environment variable:

$ env MPIHOME=$HOME/opt python setup.py build


Basic usage
===========

import boxlib
import sys

ndim = 3
size = 128

bx = boxlib.Box(lo=[1]*ndim, hi=[size]*ndim)
ba = boxlib.BoxArray(boxes=[bx])
ba.maxSize(32)

mf = boxlib.MultiFab(ba, ncomp=1, nghost=2)

a = mf[0].get_array()
a[10,10,10,0] = 22.0

print a.shape

mf.FillBoundary(0, mf1.nComp())



Technical overview
==================

The Python wrappers to BoxLib are created using SWIG.  There a few
convenience functions defined in the "boxlib" module that make
creating Boxes, BoxArrays, and MultiFabs a bit more Pythonic.

Note that the dimension of all BoxLib objects is set at compile time.
As such, PyBoxLib compiles three versions of BoxLib (for 1, 2, and 3
dimensions).  The first time you call one of the convenience routines
(Box, BoxArray etc), PyBoxLib loads the appropriate shared library.

To access the raw SWIG generate shared library, simply access the "bl"
object in boxlib, and index it with the dimensionality that you need.
For example, to call the XXX routine of the 1 dimensional BoxLib SWIG
wrapper, do the following:

>>> import boxlib
>>> boxlib.bl[1].XXX

All arrays are stored in Fortran order.  PyBoxLib exposes the raw
arrays to Python through NumPy, and the ordering is set to Fortran
order.


Known issues
============

#. Once you create a BoxLib object (Box/MultiFab etc) of a given
   dimension, all subsequent BoxLib objects must be of the same
   dimension.  In other words, once PyBoxLib loads one of the shared
   libraries for a specific dimension, it can't load another.

   In particular, the length of the IntVects becomes corrupted.  I'm
   sure there is a way around this...

#. The C++ version stores components in a non-interleaved format.
   That is, in Fortran the indexing is a(i,j,k,c).