Development Guidelines

The following are the practices that have evolved over the course of FiPy‘s development. Stray from them at your peril.

Object Oriented Design

Multiple inheritance is forbidden.

Programming Style

To the greatest extent possible, we follow PEP 8. We make the following exceptions because we had already written a great deal of code before we knew there even was a PEP 8.

Maximum Line Length

The preferred place to break around a binary operator is before the operator, not after it. Some examples:

class Rectangle(Blob):

    def __init__(self, width, height,
                 color='black', emphasis=None, highlight=0):
        if (width == 0 and height == 0
            and color == 'red' and emphasis == 'strong'
            or highlight > 100):
            raise ValueError("sorry, you lose")
        if width == 0 and height == 0 and (color == 'red'
                                           or emphasis is None):
            raise ValueError("I don't think so -- values are %s, %s"
                             % (width, height))
        Blob.__init__(self, width, height,
                      color, emphasis, highlight)

Package and Module Names

Use mixedCase rather than all-lowercase names.

Function and Method Names

Use mixedCase rather than lower_case_with_underscores names.

Any other deviations from PEP 8 should probably be corrected, but ask if you are unsure. Even the exceptions listed above are open to discussion by anybody willing to do the work of changing the existing code.

Testing

FiPy uses doctest pervasively. We have not seen a case where unittest would simplify things. As a heavily numerical code, care must be taken in checking floating-point values.

Tests should not fail as a result of a missing optional install. FiPy defines the following doctest directives to specify what conditions are needed to run the test:

GMSH

The gmsh executable, version 2.0 or greater, must on the PATH.

SCIPY

The scipy package must be importable.

TVTK

The tvtk (or enthought.tvtk) package must be importable.

SERIAL

FiPy must be running on a single processor.

PARALLEL

FiPy must be running on more than one processor.

PROCESSOR_0

Whether serial or parallel, the test will only be run on processor ID 0.

PROCESSOR_0_OF_2

The test will only be run on processor ID 0 of a two processor parallel job.

PROCESSOR_1_OF_2

The test will only be run on processor ID 1 of a two processor parallel job.

PROCESSOR_0_OF_3

The test will only be run on processor ID 0 of a three processor parallel job.

PROCESSOR_1_OF_3

The test will only be run on processor ID 1 of a three processor parallel job.

PROCESSOR_2_OF_3

The test will only be run on processor ID 2 of a three processor job.

LSMLIB

The lsmlib package must be importable.

Further directives can be defined using register_skipper(). These definitions should be placed in the file to which they pertain, e.g., GMSH is defined in fipy/meshes/gmshImport.py.