PyCC User Manual
February 9, 2006
Skavhaug
www.simula.no
Contents
About this manual
3
1 Introduction
7
A Contributing code
11
3
About this manual
Since PyCC is in a very early stage, this manual will be heavily revised. The
structure and setup of this document is inspired (and stolen) from the user
manual used in the FEniCS project, [2].
Contact
Comments, corrections and contributions to this manual are most welcome
and should be sent to
skavhaug@simula.no
5
Chapter 1
Introduction
1.1
Overview
PyCC is a Python driven PDE library for solving problems related to the
electrical activity of human heart. It consists of several small C/C++ codes
that are exposed to Python using SWIG, [5]. There are several dependencies to other software projects; we intend to implement as little as possible,
yet as much as needed, ourselves. The most important dependencies are
DOLFIN [1] (grid) and ML [3] (algebraic preconditioning).
PyCC uses state-of-the-art numerical techniques for specifying and discretizing the PDEs with the finite element method, solving the linear systems
using block preconditioned conjugate gradients methods, and for solving the
system of ODEs that constitute the cell models in the problem specification.
Flexibility and efficiency are the two main design goals of PyCC. We aim
at developing a simulator framework that is easy to extend, yet provides a
numerically efficient environment for doing large scale simulations and visualization. The flexibility is achieved by providing an application layer in
Python, where the PDE problem is posed, components are chosen and parameters set. Efficiency is ensured by implementing all the time critical
parts in C/C++. These extension modules should be made small, simple,
7
PyCC User Manual
Skavhaug
and straight forward from an implementational point of view.
8
Bibliography
[1] Dolfin, 2006. http://www.fenics.org/dolfin.
[2] FEniCS, 2006. http://www.fenics.org.
[3] ML, 2006. http://software.sandia.gov/trilinos/packages/ml/index.html.
[4] PyCC, 2006. http://home.simula.no/~{}skavhaug/heart_simulations.html.
[5] SWIG, 2006. http://www.swig.org/.
9
Appendix A
Contributing code
A.1
Getting involved
To take part in the development of PyCC, send an email to
skavhaug@simula.no
and state your intentions. Subversion access will be given to experienced developers at Simula, willing to contribute actively to the development. Otherwise, choose the tar archive available at the PyCC homepage [4]. Currently,
no such tar archive is made.
Simula internals checkout:
svn co http://svn.simula.no:40081/int/sc/pycc
External users and developers checkout:
svn co http://svn.simula.no:40081/ext/sc/pycc
11
PyCC User Manual
A.2
Skavhaug
Users without subversion access
If you have created a new module, fixed a bug somewhere, or have made a
small change which you want to contribute to PyCC, then the best way to
do so is to send us your contribution in the form of a patch. A patch is a file
which describes how to transform a file or directory structure into another.
The patch is built by comparing a version which both parties have against
the modified version which only you have.
A.2.1
Creating a patch
The tool used to create a patch is called diff and the tool used to apply
the patch is called patch. These tools are free software and are standard on
most Unix systems.
Here’s an example of how it works. Start from the latest release of PyCC,
which we here assume is release 0.1.0. You then have a directory structure
under pycc-0.1.0 where you have made modifications to some files which
you think could be useful to other users.
1. Clean up your modified directory structure to remove temporary and
binary files which will be rebuilt anyway.
2. From the parent directory, rename the PyCC directory to something
else:
# mv pycc-0.1.0 pycc-0.1.0-mod
3. Unpack the version of PyCC that you started from:
# tar zxfv pycc-0.1.0.tar.gz
4. You should now have two PyCC directory structures in your current
directory:
# ls
pycc-0.1.0
pycc-0.1.0-mod
12
PyCC User Manual
Skavhaug
5. Now use the diff tool to create the patch:
# diff -u --new-file --recursive pycc-0.1.0
pycc-0.1.0-mod > pycc-<identifier>-<date>.patch
written as one line, where <identifier> is a keyword that can be used
to identify the patch as coming from you (your username, last name,
first name, a nickname etc) and <date> is today’s date in the format
yyyy-mm-dd.
6. The patch now exists as pycc-<identifier>-<date>.patch and can
be distributed to other people who already have pycc-0.1.0 to easily
create your modified version. If the patch is large, compressing it with
for example gzip is advisable:
# gzip pycc-<identifier>-<date>.patch
A.2.2
Sending patches
Patch files should be sent to the PyCC mailing list at the address
skavhaug@simula.no
Include a short description of what your patch accomplishes. Small patches
have a better chance of being accepted, so if you are making a major contribution, please consider breaking your changes up into several small selfcontained patches if possible.
A.2.3
Applying a patch (maintainers)
Let’s say that a patch has been built relative to PyCC release 0.1.0. The
following description then shows how to apply the patch to a clean version
of release 0.1.0.
1. Unpack the version of PyCC which the patch is built relative to:
13
PyCC User Manual
Skavhaug
# tar zxfv pycc-0.1.0.tar.gz
2. Check that you have the patch pycc-<identifier>-<date>.patch
and the PyCC directory structure in the current directory:
# ls
pycc-0.1.0
pycc-<identifier>-<date>.patch
Unpack the patch file using gunzip if necessary.
3. Enter the PyCC directory structure:
# cd pycc-0.1.0
4. Apply the patch:
# patch -p1 < ../pycc-<identifier>-<date>.patch
The option -p1 strips the leading directory from the filename references
in the patch, to match the fact that we are applying the patch from
inside the directory. Another useful option to patch is --dry-run
which can be used to test the patch without actually applying it.
5. The modified version now exists as pycc-0.1.0.
A.3
Users with subversion access
Before committing changes to the subversion repository, please make sure
that your changes do not break existing code. Clean and rebuild the software, and run the tests in the tests directory. Also, make sure that your
code follows the coding convention for PyCC, is somewhat documented, and
equipped with relevant tests.
An important point is to not add binary data to the subversion repository.
Therefore, always run make clean in the src directory before adding files using file globing commands or new directories (e.g. svn add new-clean-dir
or svn add *).
14
Index
contact, 5
contributing, 11
dependencies, 7
diff, 12
patch, 12, 13
subversion, 14
svn, 14
15