PyDSTool temporary web pages

 


 

Code Topics

 


 

 

Contents

  1. Project source code
    1. Disclaimer
    2. Download options
    3. What's new?
  2. BSD License
  3. Version numbering
  4. Code conventions
  5. Available PyDSTool utilities
  6. Exception conventions
  7. Testing
  8. Code discussion

1. Project source code

1.1. Disclaimer

The PyDSTool project has grown rapidly from simple prototypes at the beginning of 2005. The package remains at the Beta stage of development partly because it contains so much legacy code from its prototype stage, and because many parts of it have not been rigorously tested. Technically the package is "research code" and should not yet be treated with expectations typical of a distributable package.

As research code, the approach taken so far has been to get the code working in the applications that we have been writing it for, in favour of aiming to make it optimally efficient. You are likely to find bugs and limitations in using our package, which you are encouraged to report to us so that we can address them. If you look at the code you may well find some "interesting" implementations of the algorithms, which may not be the cleanest, most efficient, or most Pythonic approach to have taken. We try to address these issues when we come across them and when our needs or conscience forces us to.

PyDSTool is compatible with Python 2.5-2.7, SciPy v0.7.0-0.10.0, Numpy 1.4-1.6, and MatPlotLib 0.98 onwards, as well as many previous versions. PyDSTool is not compatible with Python 3.x and will not be for some time, until all the dependent libraries become stable for that version. Version 0.83.3 of PyDSTool is the last to be compatible with "old SciPy" (v0.3.2), and will no longer be maintained. All versions will continue to be available at the SourceForge repository.

1.2. Download options

1.2.1. Sourceforge releases

The latest version available is 0.88. The current sub-release is Aug 26th, 2011 (0.88.110826).

Normally, the latest stable version is to be found as an archival image at the project files page on [WWW] SourceForge. Release notes are provided at SourceForge:

 

SourceForge.net Logo

It is recommended to delete a prior version before unzipping a new one. There is no installer for PyDSTool at this time, you simply unzip the files and follow the simple steps on the GettingStarted page.

1.2.2. Bazaar repository ("bleeding edge")

The latest (possibly unstable) version can always be found at our [WWW] bazaar repository

Read-only command is: bzr://pydstool.bzr.sourceforge.net/bzrroot/pydstool

or you can pull from the command line with: bzr pull http://pydstool.bzr.sourceforge.net/bzr/pydstool

It is likely to contain many minor fixes and improvements over the latest Sourceforge release. You can see the recent changes at the [WWW] repository.

Note that the bazaar repository that has been posted at launchpad.com is not maintained and was not uploaded by me. Please use the repository at sourceforge.net only.

 

1.3. What's new?

For a complete change log, see the [WWW] bzr changelog. Highlights of new features in the less recent versions of PyDSTool:

v 0.88, 11 Dec 2009

v 0.87, 13 Nov 2008

v 0.86, 01 June 2008

v 0.85, 11 July 2007

* PyCont can now perform continuation according to the zeros of user-defined

Patch 1, 13 Mar 2007

Unzip outside PyDSTool directory to overwrite necessary files.

v 0.84, 20 Feb 2007

This is primarily a release to bring PyDSTool up to date with numpy 1.0, "new SciPy" and Python versions later than 2.4. Major code improvements are still in development and will be released in a 0.90 version as soon as we can.

v 0.83.3, 20 Sep 2006

General:

PyCont 0.3.1:

Patch 1, 15 Jun 2006

(Unzip to PyDSTool\ directory to update files)

v0.83.2, 05 Jun 2006

General:

PyCont:

v0.83.1, 12 Mar 2006

PyCont continuation:

Pointsets and Points:

Symbolic:

Generators:

Tests:

Memory management:

Models:

2. BSD License

Copyright (C) 2008, Department of Mathematics and Statistics, Georgia State University. All rights reserved. The following BSD license applies to versions released 2005-2007, but for newer releases this has been updated in the LICENSE information provided in the PyDSTool installation zip file to reflect its hosting at Georgia State University.

Copyright (C) 2005, 2006, 2007, Department of Mathematics, Cornell University. All rights reserved.

Parts of this distribution that originate from different authors are individually marked as such. Copyright and licensing of those parts remains with the original authors.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  3. The name of Cornell University and its representatives may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY CORNELL UNIVERSITY "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CORNELL UNIVERSITY BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

3. Version numbering

We use a form of the standard GNU version numbering system of major.minor.patch for each module -- see [WWW] this rant about good version numbering practice. PyDSTool as a whole can have its own version number based on the incremental changes in its constituent modules. At "alpha"-release of a well-tested core, for the purposes of wider testing and external feedback, We have started at a global version below 1.0. Version 1.0 will be reserved for the first "beta"-type general release that has been tested in new SciPy.

For the PyDSTool package's version numbering, we use a major.minor number followed by a patch level made up of a YYMMDD date. Note the ordering, which makes the numbering sort helpfully! For example, a package version before alpha release would look like 0.5.050628. As of June 28th 2005 this scheme will also be adopted for backup directory names.

4. Code conventions

Before contributing code to the project, please read Guido van Rossum's Style Guide on the PythonResources page. It would make the code more consistent if we try to adhere to it.

More detail about the specific conventions that have been used in the core modules is given on the CodeConventions page. These are not fixed in stone, but they are a working model of some patterns that could be usefully re-used throughout the project. This is another way in which the code can appear more consistent to both end-users and future maintainers.

5. Available PyDSTool utilities

There are many common utilities available in the common.py and utils.py modules, which you are encouraged to make use of in order to re-use existing code, and make the internal interfaces more consistent. Many of these functions are listed in the Design Document on the MainProjectPage. The common.py module contains mostly internal utilities, which are of little relevance to end-users. These include functions to help deal with string parsing of user specifications, "sorting" dictionaries, verification of object properties (such as that a list of numbers is increasing, or that it only contains unique items), and a host of useful name mappings (such as NumArray type names to type codes).

Dozens of other utilities are also provided by SciPy and NumPy, and these two modules should be imported by every major PyDSTool module. It is worth a browse through these modules' API documentation to see what can be utilized before you re-invent the wheel. Particularly useful functions are:

6. Exception conventions

There are a set of PyDSTool-specific exceptions listed in the errors.py module. These are generally close counterparts of standard Python exceptions. For instance, the PyDSTool_KeyError should be raised when an end-user provides an incorrect dictionary key in the initialisation of a PyDSTool object, whereas a standard KeyError should be raised when there are inconsistencies in the dictionaries passed internally between objects (i.e. because of an intrinsic programming error).

7. Testing

All module .py files should include some basic test code for all of the major features implemented in that module. This code goes in the __main__ block at the end of the file. Look at the existing code for examples. Whenever changes are made to a module, the module should be re-run to check that these tests are still met. This is a simplified form of "unit testing" (see the link on the PythonResources page), known as "regression testing".

Additionally, more sophisticated example scripts are in the sub-directory /tests/. These test multiple features simultaneously. Please feel free to add to these.

8. Code discussion

Post and discuss code on the CodeDiscussion or the BugReporting page.

 

last edited 2009-12-28 21:21:00 by RobClewley