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.
This module can be found in the file package/subpackage/base.py. You make it available to your script by either:
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.
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:
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.
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
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.
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, ...)