jonancm / viennagrid-python

Python wrapper around ViennaGrid

ViennaGrid for Python

ViennaGrid for Python is a Python package that provides a wrapper around ViennaGrid, so that you can use ViennaGrid's capabilities from your Python programs.

The code provided here is version 0.1.0-rc.5 ViennaGrid for Python. This project uses semantic versioning for specifying the version number. In brief, this means that it uses version numbers in the form

X.Y.Z (Major.Minor.Patch)

where the following rules apply:

• Bug fixes not affecting the API increment the patch version.
• Backwards compatible API additions/changes increment the minor version.
• Backwards incompatible API changes increment the major version.

You can download ViennaGrid for Python from the project's web page. You can also download the latest development version of ViennaGrid for Python from the project's GitHub repository.

How to use ViennaGrid for Python

If you want to learn how to use ViennaGrid for Python, you should read the Sphinx documentation of the project. The introduction should present the basic concepts of ViennaGrid for Python and the tutorial explains what you need to know to start writing useful programs.

Besides, there are code examples in the source code directory tree, under doc/examples/.

Compilation instructions

If you want to compile ViennaGrid for Python from source, you may follow the installation instructions in the Sphinx documentation of the project.

Just for quick reference, we will also document it here briefly.

Dependencies

To compile ViennaGrid for Python, you will need the following software installed on your system:

• CMake 2.6 or greater (2.8 is preferred)
• Python 2.0 or greater (2.7 is preferred; Python 3 is not officially supported yet)
• Python development libraries (header files) for your Python version
• A modern C++ compiler (for development, clang 3.0 has been used)
• Boost.Python (we have used Boost.Python 1.53.0)

You will also need ViennaGrid 1.1.0, preferrably in the directory inc/ of the source code directory tree. Otherwise, you will have to edit the CMakeLists manually to change the path to ViennaGrid.

Building

Once your system satisfies these dependencias, you can create the build directory and configure the build with CMake. For example:

mkdir build
cd build
ccmake ..

After you generate the Makefiles with CMake, simply type

make

to build the software.

Installation

To install the build products, run

make install

but please notice that you will need administrator privileges to do so.

Running tests

If you want, you can run some tests on the wrapper with

make test

viennagrid-python's Issues

Add target to compile the LaTeX documentation

Add target to CMakeLists to be able to compile the LaTeX documentation (above all, the Sphinx documentation, but it could also be done for the Doxygen documentation).

Include the ViennaGrid source code in the repository / tarballs

We must think of a better way to include the ViennaGrid source code to make compilation easier.

Currently, the source code of ViennaGrid, on which ViennaGrid for Python depends, is included in the repository as a Git submodule. This is fine if the user gets and compiles the code from the repository, because they can also fetch the ViennaGrid code either by cloning and updating the submodules:

git clone https://github.com/genba/viennagrid-python.git
cd viennagrid-python/
git submodule init
git submodule update

or just by cloning with the --recursive option:

git clone --recursive https://github.com/genba/viennagrid-python.git

and they will be able to compile ViennaGrid for Python.

However, if the user downloads a tarball, the Git repository information will not be included in the tarball, and thus no submodule information will be available. In other words, the user will have to download ViennaGrid by themselves.

The script bootstrap.py intends to aid the user in this task, but it currently only updates the submodules; it doesn't download ViennaGrid separately. This must be fixed, so that the script download ViennaGrid separately when no Git repository information is available.

Besides, other approaches could be search, for example, with the ExternalProject_Add command of CMake.

Choose license for the code

A license must be chosen and its text included with the code. Choices are the LGPL or MIT license.

Wrong URL to Sphinx docs in README file

The README file on the master branch as of commit a56f23a contains a link to the Sphinx docs at http://genba.github.io/viennagrid-python/, which is clearly the wrong URL (it should be http://jonancm.github.io/viennagrid-python/).

viennagrid-python/setup.py also specifies the wrong URL.