subpackage Package

subpackage Package

Each chapter describes one of the main sub-packages of the fipy package. The sub-package fipy.package can be found in the directory fipy/package/. In a few cases, there will be packages within packages, e.g. fipy.package.subpackage located in fipy/package/subpackage/. These sub-sub-packages will not be given their own chapters; rather, their contents will be described in the chapter for their containing package.

base Module

This module can be found in the file package/subpackage/base.py. You make it available to your script by either:

import package.subpackage.base

in which case you refer to it by its full name of package.subpackage.base, or:

from package.subpackage import base

in which case you can refer simply to base.

class package.subpackage.base.Base

With very few exceptions, the name of a class will be the capitalized form of the module it resides in. Depending on how you imported the module above, you will refer to either package.subpackage.object.Object or object.Object. Alternatively, you can use:

from package.subpackage.object import Object

and then refer simply to Object. For many classes, there is a shorthand notation:

from fipy import Object

Python is an object-oriented language and the FiPy framework is composed of objects or classes. Knowledge of object-oriented programming (OOP) is not necessary to use either Python or FiPy, but a few concepts are useful. OOP involves two main ideas:

encapsulation

an object binds data with actions or “methods”. In most cases, you will not work with an object’s data directly; instead, you will set, retrieve, or manipulate the data using the object’s methods.

Methods are functions that are attached to objects and that have direct access to the data of those objects. Rather than passing the object data as an argument to a function:

fn(data, arg1, arg2, ...)

you instruct an object to invoke an appropriate method:

object.meth(arg1, arg2, ...)

If you are unfamiliar with object-oriented practices, there probably seems little advantage in this reordering. You will have to trust us that the latter is a much more powerful way to do things.

inheritance

specialized objects are derived or inherited from more general objects. Common behaviors or data are defined in base objects and specific behaviors or data are either added or modified in derived objects. Objects that declare the existence of certain methods, without actually defining what those methods do, are called “abstract”. These objects exist to define the behavior of a family of objects, but rely on their descendants to actually provide that behavior.

Unlike many object-oriented languages, Python does not prevent the creation of abstract objects, but we will include a notice like

Attention

This class is abstract. Always create one of its subclasses.

for abstract classes which should be used for documentation but never actually created in a FiPy script.

method1()

This is one thing that you can instruct any object that derives from Base to do, by calling myObjectDerivedFromBase.method1()

Parameters :

• self: this special argument refers to the object that is being created.

  Attention

  self is supplied automatically by the Python interpreter to all methods. You don’t need to (and should not) specify it yourself.

method2()

This is another thing that you can instruct any object that derives from Base to do.

object Module

class package.subpackage.object.Object(arg1, arg2=None, arg3='string')

Bases: package.subpackage.base.Base

This method, like all those whose names begin and end with “__” are special. You won’t ever need to call these methods directly, but Python will invoke them for you under certain circumstances, which are described in the Python Reference Manual: Special Method Names.

As an example, the __init__() method is invoked when you create an object, as in:

obj = Object(arg1=something, arg3=somethingElse, ...)

Parameters :

• arg1: this argument is required. Python supports named arguments, so you must either list the value for arg1 first:

  obj = Object(val1, val2)
  

  or you can specify the arguments in any order, as long as they are named:

  obj = Object(arg2=val2, arg1=val1)
  

• arg2: this argument may be omitted, in which case it will be assigned a default value of None. If you do not use named arguments (and we recommend that you do), all required arguments must be specified before any optional arguments.

• arg3: this argument may be omitted, in which case it will be assigned a default value of 'string'.

method2()

Object provides a new definition for the behavior of method2(), whereas the behavior of method1() is defined by Base.