Commit e6ae9762 authored by Kwant authors's avatar Kwant authors Committed by Christoph Groth
Browse files

development leading up to version 0.1

parent f9bda42a
*~
MANIFEST
*.pyc
*.so
/kwant/*/*.c
/kwant/_static_version.py
/build
/dist
/doc/build
/doc/source/reference/generated/
/doc/source/images/*.png
/doc/source/images/*.pdf
/doc/source/images/.*_flag
# This file specifies the files to be included in the source distribution
# in addition to the default ones.
recursive-include kwant *.pxd
recursive-include kwant *.h
recursive-include kwant test_*.py
include TODO.txt
recursive-include examples *.py
include doc/other/*[a-zA-Z]
include doc/Makefile
recursive-include doc/source *.rst *.py *.svg
recursive-include doc/source/_static *[a-zA-Z]
recursive-include doc/templates *[a-zA-Z]
prune doc/source/reference/generated
recursive-include doc/sphinxext *.py *.txt *.in
=============================================================
kwant, a package for numerical quantum transport calculations
=============================================================
Licence
=======
This software is NOT TO BE DISTRIBUTED, neither in part nor as a whole.
The only exception to this is the ``doc/sphinxext`` subdirectory, which is free
software. (See the file ``LICENSE.txt`` in that subdirectory.)
Installation
============
The prerequisites are
- More or less current versions of `Python <http://python.org>`_ and `SciPy
<http://scipy.org>`_. Python 2.6 and scipy 0.7.2 should be enough.
- `Cython <http://cython.org/>`_ -- Version 0.13 works for us.
optional:
- `pycairo <http://cairographics.org/pycairo/>`_ (for plotting)
- `matplotlib <http://matplotlib.sourceforge.net/>`_ (for some of the
examples)
kwant can be build and installed using distutils, following standard python
conventions. To build and install, run the following commands in the root
directory of the package. ::
python setup.py build
python setup.py install
The second command has to be run as root (e.g. prefixing it with ``sudo``). By
default the package will be installed under ``/usr/local``. You can change
this using the ``--prefix`` option, e.g.::
python setup.py install --prefix=/opt
If you would like to install kwant into your home directory only you can use ::
python setup.py install --home=~
This does not require superuser priviledges. If you install kwant in this way
be sure to tell python where to find it. This can be done by setting the
``PYTHONPATH`` environment variable::
export PYTHONPATH=$HOME/lib/python
You can make this setting permanent by adding this line to your the file
``.bashrc`` in your home directory.
To check successful installation try executing some examples in the
``examples`` subdirectory.
Documentation
=============
To build the documentation, kwant has to be installed as described in the
previous section. The `sphinx documentation generator
<http://sphinx.pocoo.org/>`_ is required.
HTML documentation can be built by entering the ``doc`` subdirectory of the
kwant package and executing ``make html``. PDF documentation is generated by
executing ``make latex`` followed by a ``make all-pdf`` in ``doc/build/latex``.
Because of some quirks of how sphinx works, it might be necessary to execute
``make clean`` between building HTML and PDF documentation. If this is not
done, sphinx might mistakenly use PNG files for PDF output.
Please consult the documentation for further information on how to use kwant.
Hacking
=======
To work on the library itself it is useful to build it in-place. This can be
done with the following command ::
python setup.py build_ext -i
The ``kwant`` subdirectory of the source distribution will be thus turned into
a proper python package which can be imported. To be able to import kwant from
within python, one can either work in the root directory of the distribution
(where the subdirectory ``kwant`` is located), or make a (symbolic) link from
somewhere in the Python search path to the the package subdirectory.
Some conventions to keep in mind:
* Please keep the code consistent by adhering to the already used naming and
formatting conventions. We generally follow the `"Style Guide for Python
Code" <http://www.python.org/dev/peps/pep-0008/>`_ and the `"Docstring
Conventions" <http://www.python.org/dev/peps/pep-0257/>`_.
* Write tests for all the important functionality you add. Be sure not to
break existing tests.
Tests
=====
We use the `nose testing framework
<http://somethingaboutorange.com/mrl/projects/nose/>`_. To run the tests,
execute the command ``nosetests`` from the root directory of the package after
it has been built in place.
Roughly in order of importance. -*-org-*-
* Define a few benchmarks and check performance. Optimize the code.
* Write a fast tiny array module.
(If this turns out to be a performance bottleneck.)
* Provide support for calculating and nicely plotting LDOS.
Make a tutorial example for this.
* Allow attaching lead with further then nearest slice hoppings.
The most easy way to do this is increasing the period of the lead.
* Optionally show site coordinates when plotting a system.
* Add support for easily adding magnetic field to a system.
* Generalize InfiniteSystem to multiple directions.
* Add support for optimization of lead fundamental domains.
* Write a module to generate "functional" random numbers.
This is a good starting point:
http://www.cs.umbc.edu/~olano/papers/GPUTEA.pdf
* Write a RGF solver which uses graph/slicer.
* Implement the C solver interface.
* Wrap TB_SIM as a solver.
* Wrap umfpack or some other sparse linear algebra library with Cython.
Use it directly in sparse solver. This will allow to fine-tune the solution
of sparse systems.
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# In difference to the original Makefile, we convert all SVG files to PDF for
# LaTeX output. For HTML output, we don't create PNGs but rather use the SVG
# files directly.
IMAGESOURCES = $(shell find source -name "*.svg")
GENERATEDPDF = $(patsubst %.svg, %.pdf, $(IMAGESOURCES))
# Tutorial images.
TUTORIAL1A_IMAGES = source/images/tutorial1a_result.png source/images/tutorial1a_result.pdf source/images/tutorial1a_sys.png source/images/tutorial1a_sys.pdf
TUTORIAL2A_IMAGES = source/images/tutorial2a_result.png source/images/tutorial2a_result.pdf
TUTORIAL2B_IMAGES = source/images/tutorial2b_result.png source/images/tutorial2b_result.pdf
TUTORIAL2C_IMAGES = source/images/tutorial2c_result.png source/images/tutorial2c_result.pdf source/images/tutorial2c_sys.png source/images/tutorial2c_sys.pdf source/images/tutorial2c_note1.png source/images/tutorial2c_note1.pdf source/images/tutorial2c_note2.png source/images/tutorial2c_note2.pdf
TUTORIAL3A_IMAGES = source/images/tutorial3a_result.png source/images/tutorial3a_result.pdf
TUTORIAL3B_IMAGES = source/images/tutorial3b_result.png source/images/tutorial3b_result.pdf source/images/tutorial3b_sys.png source/images/tutorial3b_sys.pdf
TUTORIAL4_IMAGES = source/images/tutorial4_result.png source/images/tutorial4_result.pdf source/images/tutorial4_sys1.png source/images/tutorial4_sys1.pdf source/images/tutorial4_sys2.png source/images/tutorial4_sys2.pdf source/images/tutorial4_bs.png source/images/tutorial4_bs.pdf
ALL_TUTORIAL_IMAGES = $(TUTORIAL1A_IMAGES) $(TUTORIAL2A_IMAGES) $(TUTORIAL2B_IMAGES) $(TUTORIAL2C_IMAGES) $(TUTORIAL3A_IMAGES) $(TUTORIAL3B_IMAGES) $(TUTORIAL4_IMAGES)
.PHONY: help clean realclean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/* $(GENERATEDPDF)
-rm -rf source/reference/generated
realclean: clean
-rm -f $(ALL_TUTORIAL_IMAGES) source/images/.*_flag
html: $(ALL_TUTORIAL_IMAGES)
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml: $(ALL_TUTORIAL_IMAGES)
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
pickle: $(ALL_TUTORIAL_IMAGES)
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json: $(ALL_TUTORIAL_IMAGES)
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp: $(ALL_TUTORIAL_IMAGES)
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp: $(ALL_TUTORIAL_IMAGES)
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/kwant.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/kwant.qhc"
latex: $(GENERATEDPDF) $(ALL_TUTORIAL_IMAGES)
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
%.pdf: %.svg
inkscape --export-pdf=$@ $<
# Generation of tutorial images. This requires some serious make trickery, see
# http://article.gmane.org/gmane.comp.gnu.make.general/5806
$(TUTORIAL1A_IMAGES): source/images/.tutorial1a_flag
@:
source/images/.tutorial1a_flag: source/images/tutorial1a.py
cd source/images/ && python tutorial1a.py
touch source/images/.tutorial1a_flag
$(TUTORIAL2A_IMAGES): source/images/.tutorial2a_flag
@:
source/images/.tutorial2a_flag: source/images/tutorial2a.py
cd source/images/ && python tutorial2a.py
touch source/images/.tutorial2a_flag
$(TUTORIAL2B_IMAGES): source/images/.tutorial2b_flag
@:
source/images/.tutorial2b_flag: source/images/tutorial2b.py
cd source/images/ && python tutorial2b.py
touch source/images/.tutorial2b_flag
$(TUTORIAL2C_IMAGES): source/images/.tutorial2c_flag
@:
source/images/.tutorial2c_flag: source/images/tutorial2c.py
cd source/images/ && python tutorial2c.py
touch source/images/.tutorial2c_flag
$(TUTORIAL3A_IMAGES): source/images/.tutorial3a_flag
@:
source/images/.tutorial3a_flag: source/images/tutorial3a.py
cd source/images/ && python tutorial3a.py
touch source/images/.tutorial3a_flag
$(TUTORIAL3B_IMAGES): source/images/.tutorial3b_flag
@:
source/images/.tutorial3b_flag: source/images/tutorial3b.py
cd source/images/ && python tutorial3b.py
touch source/images/.tutorial3b_flag
$(TUTORIAL4_IMAGES): source/images/.tutorial4_flag
@:
source/images/.tutorial4_flag: source/images/tutorial4.py
cd source/images/ && python tutorial4.py
touch source/images/.tutorial4_flag
@import "default.css";
/**
* Spacing fixes
div.body p, div.body dd, div.body li {
line-height: 125%;
}
ul.simple {
margin-top: 0;
margin-bottom: 0;
padding-top: 0;
padding-bottom: 0;
}
*/
/* spacing around blockquoted fields in parameters/attributes/returns */
/*Essential. Otherwise there is way too much space around*/
td.field-body > blockquote {
margin-top: 0.1em;
margin-bottom: 0.5em;
}
/* THE NEXT TWO ARE EVENTUALLY IMPORTANT I THINK */
/* spacing around example code
div.highlight > pre {
padding: 2px 5px 2px 5px;
}
*/
/* spacing in see also definition lists
dl.last > dd {
margin-top: 1px;
margin-bottom: 5px;
margin-left: 30px;
}
*/
/* hide overflowing content in the sidebar
div.sphinxsidebarwrapper p.topless {
overflow: hidden;
}
*/
/**
* Hide dummy toctrees
ul {
padding-top: 0;
padding-bottom: 0;
margin-top: 0;
margin-bottom: 0;
}
ul li {
padding-top: 0;
padding-bottom: 0;
margin-top: 0;
margin-bottom: 0;
}
ul li a.reference {
padding-top: 0;
padding-bottom: 0;
margin-top: 0;
margin-bottom: 0;
}
*/
/**
* Make high-level subsections easier to distinguish from top-level ones
div.body h3 {
background-color: transparent;
}
div.body h4 {
border: none;
background-color: transparent;
}
*/
/**
* Scipy colors
body {
background-color: rgb(100,135,220);
}
div.document {
background-color: rgb(230,230,230);
}
div.sphinxsidebar {
background-color: rgb(230,230,230);
}
div.related {
background-color: rgb(100,135,220);
}
div.sphinxsidebar h3 {
color: rgb(0,102,204);
}
div.sphinxsidebar h3 a {
color: rgb(0,102,204);
}
div.sphinxsidebar h4 {
color: rgb(0,82,194);
}
div.sphinxsidebar p {
color: black;
}
div.sphinxsidebar a {
color: #355f7c;
}
div.sphinxsidebar ul.want-points {
list-style: disc;
}
*/
.field-list th {
color: rgb(0,50,150);
background-color: #EEE8AA;
white-space: nowrap; /*Essential. Otherwise the colons can break
into a new line*/
}
/**
* Extra admonitions
div.tip {
background-color: #ffffe4;
border: 1px solid #ee6;
}
div.plot-output {
clear-after: both;
}
div.plot-output .figure {
float: left;
text-align: center;
margin-bottom: 0;
padding-bottom: 0;
}
div.plot-output .caption {
margin-top: 2;
padding-top: 0;
}
div.plot-output p.admonition-title {
display: none;
}
div.plot-output:after {
content: "";
display: block;
height: 0;
clear: both;
}
*/
/*
div.admonition-example {
background-color: #e4ffe4;
border: 1px solid #ccc;
}*/
/**
* Styling for field lists
*/
table.field-list th {
border-left: 2px solid #999 !important;
padding-left: 5px;
}
table.field-list {
border-collapse: separate; /*Essential. Otherwise Parameters and Returns
are sharing one solid colored field. That looks
weird.*/
border-spacing: 10px;
}
/**
* Styling for footnotes
table.footnote td, table.footnote th {
border: none;
}
*/
div.specialnote-title {
font-size: 105%;
font-weight: bold;
font-color: #3B4D3C;
background-color: #DCE4DC;
padding: 1em;
padding-top: 0.4em;
padding-bottom: 0.4em;
margin-top: 1em;
margin-bottom: 0px;
border-width: 1px;
border-color: #546C55;
border-style: solid;
}
div.specialnote-body {
background-color: #DCE4DC;
padding: 1em;
padding-top: 0.1em;
padding-bottom: 0.4em;
margin-top: 0px;
border-width: 1px;
border-top-width: 0px;
border-color: #546C55;
border-style: solid;
}
function togglediv(id) {
var buttontext;
buttontext = $("#" + id + "-button").text();
if(buttontext == 'show') {
$("#" + id + "-button").text('hide');
}
else {
$("#" + id + "-button").text('show');
}
$("#" + id + "-body").slideToggle('swing');
}
# -*- coding: utf-8 -*-
#
# kwant documentation build configuration file, created by
# sphinx-quickstart on Tue Jan 11 09:39:28 2011.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
import kwant
# -- General configuration -----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
sys.path.insert(0, os.path.abspath('../sphinxext'))
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary',
'sphinx.ext.todo', 'sphinx.ext.pngmath', 'numpydoc',
'kwantdoc']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['../templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'kwant'
copyright = u'2011-2012, A. R. Akhmerov, C. W. Groth, X. Waintal, M. Wimmer'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The full version, including alpha/beta/rc tags.
release = kwant.version.version[:]
for i, s in enumerate(release):
if s not in '0123456790.':
break
# The short X.Y version.
version = release[:i]
# The language for content autogenerated by