Moved scipy directory to numpy

1 files changed, 457 insertions, 0 deletions

diff --git a/numpy/f2py/docs/README.txt b/numpy/f2py/docs/README.txt
new file mode 100644
index 000000000..fc7149645
--- /dev/null
+++ b/numpy/f2py/docs/README.txt
@@ -0,0 +1,457 @@
+.. -*- rest -*-
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ F2PY: Fortran to Python interface generator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:Author: Pearu Peterson <pearu@cens.ioc.ee>
+:License: LGPL_.
+:Web-site: http://cens.ioc.ee/projects/f2py2e/
+:Discussions to: `f2py-users mailing list`_
+:Documentation: `User's Guide`__, FAQ__
+:Platforms: All
+:Date: $Date: 2005/01/30 18:54:53 $
+
+.. _f2py-users mailing list: http://cens.ioc.ee/mailman/listinfo/f2py-users/
+__ usersguide/index.html
+__ FAQ.html
+
+-------------------------------
+
+.. topic:: NEWS!!!
+
+  January 30, 2005
+
+    Latest F2PY release (version 2.45.241_1926).
+    New features: wrapping unsigned integers, support for ``.pyf.src`` template files,
+    callback arguments can now be CObjects, fortran objects, built-in functions.
+    Introduced ``intent(aux)`` attribute. Wrapped objects have ``_cpointer``
+    attribute holding C pointer to wrapped functions or variables.
+    Many bug fixes and improvements, updated documentation.
+    `Differences with the previous release (version 2.43.239_1831)`__.
+
+  __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.163&r2=1.137&f=h
+
+  October 4, 2004
+    F2PY bug fix release (version 2.43.239_1831).
+    Better support for 64-bit platforms.
+    Introduced ``--help-link`` and ``--link-<resource>`` options.
+    Bug fixes.
+    `Differences with the previous release (version 2.43.239_1806)`__.
+
+  __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.137&r2=1.131&f=h
+
+  September 25, 2004
+    Latest F2PY release (version 2.43.239_1806). 
+    Support for ``ENTRY`` statement. New attributes:
+    ``intent(inplace)``, ``intent(callback)``. Supports Numarray 1.1.
+    Introduced ``-*- fix -*-`` header content. Improved ``PARAMETER`` support.
+    Documentation updates. `Differences with the previous release
+    (version 2.39.235-1693)`__.
+
+  __ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt.diff?r1=1.131&r2=1.98&f=h
+
+  `History of NEWS`__
+
+  __ OLDNEWS.html
+
+-------------------------------
+
+.. Contents::
+
+==============
+ Introduction
+==============
+
+The purpose of the F2PY --*Fortran to Python interface generator*--
+project is to provide connection between Python_ and Fortran
+languages. F2PY is a Python extension tool for creating Python C/API
+modules from (handwritten or F2PY generated) signature files (or
+directly from Fortran sources). The generated extension modules
+facilitate:
+
+* Calling Fortran 77/90/95, Fortran 90/95 module, and C functions from
+  Python.
+
+* Accessing Fortran 77 ``COMMON`` blocks and Fortran 90/95 module
+  data (including allocatable arrays) from Python.
+
+* Calling Python functions from Fortran or C (call-backs).
+
+* Automatically handling the difference in the data storage order of
+  multi-dimensional Fortran and Numerical Python (i.e. C) arrays.
+
+In addition, F2PY can build the generated extension modules to shared
+libraries with one command. F2PY uses the ``scipy_distutils`` module
+from SciPy_ that supports number of major Fortran compilers.
+
+..
+  (see `COMPILERS.txt`_ for more information).
+
+F2PY generated extension modules depend on NumPy_ package that
+provides fast multi-dimensional array language facility to Python.
+
+
+---------------
+ Main features
+---------------
+
+Here follows a more detailed list of F2PY features:
+
+* F2PY scans real Fortran codes to produce the so-called signature
+  files (.pyf files). The signature files contain all the information
+  (function names, arguments and their types, etc.)  that is needed to
+  construct Python bindings to Fortran (or C) functions.
+
+  The syntax of signature files is borrowed from the
+  Fortran 90/95 language specification and has some F2PY specific
+  extensions. The signature files can be modified to dictate how
+  Fortran (or C) programs are called from Python:
+
+    + F2PY solves dependencies between arguments (this is relevant for
+      the order of initializing variables in extension modules).
+
+    + Arguments can be specified to be optional or hidden that
+      simplifies calling Fortran programs from Python considerably.
+
+    + In principle, one can design any Python signature for a given
+      Fortran function, e.g. change the order arguments, introduce
+      auxiliary arguments, hide the arguments, process the arguments
+      before passing to Fortran, return arguments as output of F2PY
+      generated functions, etc.
+
+* F2PY automatically generates __doc__ strings (and optionally LaTeX
+  documentation) for extension modules.
+
+* F2PY generated functions accept arbitrary (but sensible) Python
+  objects as arguments. The F2PY interface automatically takes care of
+  type-casting and handling of non-contiguous arrays.
+
+* The following Fortran constructs are recognized by F2PY:
+
+  + All basic Fortran types::
+
+      integer[ | *1 | *2 | *4 | *8 ], logical[ | *1 | *2 | *4 | *8 ]
+      integer*([ -1 | -2 | -4 | -8 ])
+      character[ | *(*) | *1 | *2 | *3 | ... ]
+      real[ | *4 | *8 | *16 ], double precision
+      complex[ | *8 | *16 | *32 ]
+
+    Negative ``integer`` kinds are used to wrap unsigned integers.
+
+  + Multi-dimensional arrays of all basic types with the following
+    dimension specifications::
+
+      <dim> | <start>:<end> | * | :
+
+  + Attributes and statements::
+     
+      intent([ in | inout | out | hide | in,out | inout,out | c |
+               copy | cache | callback | inplace | aux ])
+      dimension(<dimspec>)
+      common, parameter
+      allocatable
+      optional, required, external
+      depend([<names>])
+      check([<C-booleanexpr>])
+      note(<LaTeX text>)
+      usercode, callstatement, callprotoargument, threadsafe, fortranname
+      pymethoddef
+      entry
+
+* Because there are only little (and easily handleable) differences
+  between calling C and Fortran functions from F2PY generated
+  extension modules, then F2PY is also well suited for wrapping C
+  libraries to Python.
+
+* Practice has shown that F2PY generated interfaces (to C or Fortran
+  functions) are less error prone and even more efficient than
+  handwritten extension modules. The F2PY generated interfaces are
+  easy to maintain and any future optimization of F2PY generated
+  interfaces transparently apply to extension modules by just
+  regenerating them with the latest version of F2PY.
+
+* `F2PY Users Guide and Reference Manual`_
+
+
+===============
+ Prerequisites
+===============
+
+F2PY requires the following software installed:
+
+* Python_ (versions 1.5.2 or later; 2.1 and up are recommended).
+  You must have python-dev package installed.
+* NumPy_ (versions 13 or later; 20.x, 21.x, 22.x, 23.x are recommended)
+* Numarray_ (version 0.9 and up), optional, partial support.
+* Scipy_distutils (version 0.2.2 and up are recommended) from SciPy_
+  project. Get it from Scipy CVS or download it below.
+
+Python 1.x users also need distutils_.
+
+Of course, to build extension modules, you'll need also working C
+and/or Fortran compilers installed.
+
+==========
+ Download
+==========
+
+You can download the sources for the latest F2PY and scipy_distutils
+releases as:
+
+* `2.x`__/`F2PY-2-latest.tar.gz`__
+* `2.x`__/`scipy_distutils-latest.tar.gz`__
+
+Windows users might be interested in Win32 installer for F2PY and
+Scipy_distutils (these installers are built using Python 2.3):
+
+* `2.x`__/`F2PY-2-latest.win32.exe`__
+* `2.x`__/`scipy_distutils-latest.win32.exe`__
+
+Older releases are also available in the directories
+`rel-0.x`__, `rel-1.x`__, `rel-2.x`__, `rel-3.x`__, `rel-4.x`__, `rel-5.x`__,
+if you need them.
+
+.. __: 2.x/
+.. __: 2.x/F2PY-2-latest.tar.gz
+.. __: 2.x/
+.. __: 2.x/scipy_distutils-latest.tar.gz
+.. __: 2.x/
+.. __: 2.x/F2PY-2-latest.win32.exe
+.. __: 2.x/
+.. __: 2.x/scipy_distutils-latest.win32.exe
+.. __: rel-0.x
+.. __: rel-1.x
+.. __: rel-2.x
+.. __: rel-3.x
+.. __: rel-4.x
+.. __: rel-5.x
+
+Development version of F2PY from CVS is available as `f2py2e.tar.gz`__.
+
+__ http://cens.ioc.ee/cgi-bin/viewcvs.cgi/python/f2py2e/f2py2e.tar.gz?tarball=1
+
+Debian Sid users can simply install ``python-f2py`` package.
+
+==============
+ Installation
+==============
+
+Unpack the source file, change to directrory ``F2PY-?-???/`` and run
+(you may need to become a root)::
+
+  python setup.py install
+
+The F2PY installation installs a Python package ``f2py2e`` to your
+Python ``site-packages`` directory and a script ``f2py`` to your
+Python executable path. 
+
+See also Installation__ section in `F2PY FAQ`_.
+
+.. __: FAQ.html#installation
+
+Similarly, to install ``scipy_distutils``, unpack its tar-ball and run::
+
+  python setup.py install
+
+=======
+ Usage
+=======
+
+To check if F2PY is installed correctly, run
+::
+
+  f2py
+
+without any arguments. This should print out the usage information of
+the ``f2py`` program.
+
+Next, try out the following three steps:
+
+1) Create a Fortran file `hello.f`__ that contains::
+
+    C File hello.f
+          subroutine foo (a)
+          integer a
+          print*, "Hello from Fortran!"
+          print*, "a=",a
+          end
+
+__ hello.f
+
+2) Run
+
+  ::
+  
+    f2py -c -m hello hello.f
+
+  This will build an extension module ``hello.so`` (or ``hello.sl``,
+  or ``hello.pyd``, etc. depending on your platform) into the current
+  directory.
+
+3) Now in Python try::
+
+    >>> import hello
+    >>> print hello.__doc__
+    >>> print hello.foo.__doc__
+    >>> hello.foo(4)     
+     Hello from Fortran!
+     a= 4
+    >>> 
+
+If the above works, then you can try out more thorough 
+`F2PY unit tests`__ and read the `F2PY Users Guide and Reference Manual`_.
+
+__ FAQ.html#q-how-to-test-if-f2py-is-working-correctly
+
+===============
+ Documentation
+===============
+
+The documentation of the F2PY project is collected in ``f2py2e/docs/``
+directory. It contains the following documents:
+
+`README.txt`_ (in CVS__)
+  The first thing to read about F2PY -- this document.
+
+__ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/README.txt?rev=HEAD&content-type=text/x-cvsweb-markup
+
+`usersguide/index.txt`_, `usersguide/f2py_usersguide.pdf`_
+  F2PY Users Guide and Reference Manual. Contains lots of examples.
+
+`FAQ.txt`_ (in CVS__)
+  F2PY Frequently Asked Questions.
+
+__ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/FAQ.txt?rev=HEAD&content-type=text/x-cvsweb-markup
+
+`TESTING.txt`_ (in CVS__)
+  About F2PY testing site. What tests are available and how to run them.
+
+__ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/TESTING.txt?rev=HEAD&content-type=text/x-cvsweb-markup
+
+`HISTORY.txt`_ (in CVS__)
+  A list of latest changes in F2PY. This is the most up-to-date
+  document on F2PY.
+
+__ http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt?rev=HEAD&content-type=text/x-cvsweb-markup
+
+`THANKS.txt`_
+  Acknowledgments.
+
+..
+  `COMPILERS.txt`_
+  Compiler and platform specific notes.
+
+===============
+ Mailing list
+===============
+
+A mailing list f2py-users@cens.ioc.ee is open for F2PY releated
+discussion/questions/etc.
+
+* `Subscribe..`__ 
+* `Archives..`__
+
+__ http://cens.ioc.ee/mailman/listinfo/f2py-users
+__ http://cens.ioc.ee/pipermail/f2py-users
+
+
+=====
+ CVS
+=====
+
+F2PY is being developed under CVS_. The CVS version of F2PY can be
+obtained as follows:
+
+1) First you need to login (the password is ``guest``)::
+
+    cvs -d :pserver:anonymous@cens.ioc.ee:/home/cvs login
+
+2) and then do the checkout::
+
+    cvs -z6 -d :pserver:anonymous@cens.ioc.ee:/home/cvs checkout f2py2e
+
+3) You can update your local F2PY tree ``f2py2e/`` by executing::
+
+    cvs -z6 update -P -d
+
+You can browse the `F2PY CVS`_ repository.
+
+===============
+ Contributions
+===============
+
+* `A short introduction to F2PY`__ by Pierre Schnizer.
+
+* `F2PY notes`__ by Fernando Perez.
+
+* `Debian packages of F2PY`__ by José Fonseca. [OBSOLETE, Debian Sid
+  ships python-f2py package]
+
+__ http://fubphpc.tu-graz.ac.at/~pierre/f2py_tutorial.tar.gz
+__ http://cens.ioc.ee/pipermail/f2py-users/2003-April/000472.html
+__ http://jrfonseca.dyndns.org/debian/
+
+
+===============
+ Related sites
+===============
+
+* `Numerical Python`_ -- adds a fast array facility to the Python language.
+* Pyfort_ -- A Python-Fortran connection tool.
+* SciPy_ -- An open source library of scientific tools for Python.
+* `Scientific Python`_ -- A collection of Python modules that are
+  useful for scientific computing.
+* `The Fortran Company`_ -- A place to find products, services, and general
+  information related to the Fortran programming language.
+* `American National Standard Programming Language FORTRAN ANSI(R) X3.9-1978`__
+* `J3`_ -- The US Fortran standards committee.
+* SWIG_ -- A software development tool that connects programs written
+  in C and C++ with a variety of high-level programming languages. 
+* `Mathtools.net`_ -- A technical computing portal for all scientific
+  and engineering needs. 
+
+.. __: http://www.fortran.com/fortran/F77_std/rjcnf.html
+
+.. References
+   ==========
+
+
+.. _F2PY Users Guide and Reference Manual: usersguide/index.html
+.. _usersguide/index.txt: usersguide/index.html
+.. _usersguide/f2py_usersguide.pdf: usersguide/f2py_usersguide.pdf
+.. _README.txt: README.html
+.. _COMPILERS.txt: COMPILERS.html
+.. _F2PY FAQ:
+.. _FAQ.txt: FAQ.html
+.. _HISTORY.txt: HISTORY.html
+.. _HISTORY.txt from CVS: http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/docs/HISTORY.txt?rev=HEAD&content-type=text/x-cvsweb-markup
+.. _THANKS.txt: THANKS.html
+.. _TESTING.txt: TESTING.html
+.. _F2PY CVS2: http://cens.ioc.ee/cgi-bin/cvsweb/python/f2py2e/
+.. _F2PY CVS: http://cens.ioc.ee/cgi-bin/viewcvs.cgi/python/f2py2e/
+
+.. _CVS: http://www.cvshome.org/
+.. _Python: http://www.python.org/
+.. _SciPy: http://www.scipy.org/
+.. _NumPy: http://www.numpy.org/
+.. _Numarray: http://www.stsci.edu/resources/software_hardware/numarray
+.. _docutils: http://docutils.sourceforge.net/
+.. _distutils: http://www.python.org/sigs/distutils-sig/
+.. _LGPL: http://www.fsf.org/copyleft/lesser.html
+.. _Numerical Python: http://www.numpy.org/
+.. _Pyfort: http://pyfortran.sourceforge.net/
+.. _Scientific Python: 
+   http://starship.python.net/crew/hinsen/scientific.html
+.. _The Fortran Company: http://www.fortran.com/fortran/
+.. _J3: http://www.j3-fortran.org/
+.. _Mathtools.net: http://www.mathtools.net/
+.. _SWIG: http://www.swig.org/
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End: