From 175c7ce367b15157dc05e11cc8fb888a0a407d27 Mon Sep 17 00:00:00 2001
From: Anton Akhmerov <anton.akhmerov@gmail.com>
Date: Sun, 8 Sep 2013 10:49:28 +0200
Subject: [PATCH] start updating the website
---
content/citing.txt | 34 +++---
content/contribute.txt | 78 ++++++++++++++
content/download.txt | 21 ----
content/install.txt | 227 +++++++++++++++++++++++++++++++++++++++++
templates/base.mako | 5 +-
5 files changed, 330 insertions(+), 35 deletions(-)
create mode 100644 content/contribute.txt
delete mode 100644 content/download.txt
create mode 100644 content/install.txt
diff --git a/content/citing.txt b/content/citing.txt
index abbd525..9f7d1a9 100644
--- a/content/citing.txt
+++ b/content/citing.txt
@@ -1,15 +1,25 @@
Citing kwant
============
-While kwant is not publicly released yet, we hope that once it is, it will be
-used for research. If kwant contributes to a project that leads to a scientific
-publication, please acknowledge this fact by citing the project. The kwant
-paper has not been published yet, but will be announced at this place once
-published: please check.
-
-The principal developers of kwant are:
-
-* Christoph W. Groth (SPSMS-INAC-CEA Grenoble)
-* Michael Wimmer (Leiden University)
-* `Anton R. Akhmerov <http://antonakhmerov.org>`__ (Harvard University, Leiden University)
-* Xavier Waintal (SPSMS-INAC-CEA Grenoble)
+We provide Kwant as free software under a BSD license as a
+service to the physics community. If you have used Kwant for work that has lead
+to a scientific publication, please mention this explicitly in the text body.
+In addition, we ask you to cite the main paper that introduces Kwant:
+
+ The reference will be provided here once it is available (soon).
+
+If you have profited from the quantum transport functionality of Kwant, please
+also cite the upcoming paper that describes the relevant algorithms. The
+reference will also be added here once it is available.
+
+Kwant owes much of its current performance to the use of the `MUMPS
+<http://graal.ens-lyon.fr/MUMPS/>`_ library for solving systems of sparse linear
+equations. If you have done high-performance calculations, we suggest citing
+
+ P. R. Amestoy, I. S. Duff, J. S. Koster, J. Y. L’Excellent, SIAM. J. Matrix
+ Anal. & Appl. **23** (1), 15 (2001).
+
+Finally, if you use the routine for generation of circular ensembles of random
+matrices, please cite
+
+ \F. Mezzadri, Notices Am. Math. Soc. **54**, 592 (2007).
diff --git a/content/contribute.txt b/content/contribute.txt
new file mode 100644
index 0000000..868100c
--- /dev/null
+++ b/content/contribute.txt
@@ -0,0 +1,78 @@
+============================================
+Contributing to Kwant and reporting problems
+============================================
+
+We see Kwant not just as a package with fixed functionality, but rather as a
+framework for implementing different physics-related algorithms using a common
+set of concepts and, if possible, a shared interface. We have designed it
+leaving room for growth, and plan to keep extending it.
+
+External contributions to Kwant are highly welcome. You can help to advance the
+project not only by writing code, but also by reporting bugs, and
+fixing/improving the documentation. A mailing list TODO: add link (also
+usable through a web interface (TODO: add link) ) is available for discussions.
+
+If you have some code that works well with Kwant, or extends it in some useful
+way, please consider sharing it. Any external contribution will be clearly
+marked as such, and relevant papers will be added to the list of `suggested
+acknowledgements </citing.html>`_. The complete development history is
+available through a `web interface <http://git.kwant-project.org/kwant>`_.
+
+Reporiting bugs
+---------------
+
+If you encounter a problem with Kwant, first try to reproduce it with as simple
+a system as possible. Double-check with the documentation that what you observe
+is actually a bug in Kwant. If you think it is, please check whether the problem
+is already known by searching the mailing list. (TODO: tell how).
+
+If the problem is not known yet, please email a bug report to the `Kwant mailing
+list <mailto:kwant-discuss@kwant-project.org>`_. A report should contain:
+
+* The versions of software you are using (Kwant, Python, operating system, etc.)
+
+* A description of the problem, i.e. what exactly goes wrong.
+
+* Enough information to reproduce the bug, preferably in the form of a simple
+ script.
+
+How to contribute
+-----------------
+
+We use the version control system `Git <http://git-scm.com/>`_ to coordinate the
+development of Kwant. If you are new to Git, we invite you to learn its basics.
+(There's a plethora of information available on the Web.) Kwant's Git
+repository contains not only the source code, but also all of the reference
+documentation and the tutorial.
+
+It is best to base your work on the latest version of Kwant::
+
+ git clone http://git.kwant-project.org/kwant
+
+Then you can modify the code, and build Kwant and the documentation as described
+in the `installation instructions </install.html>`_.
+
+Some things to keep in mind:
+
+* Please keep the code consistent by adhering to the prevailing naming and
+ formatting conventions. We generally follow the `"Style Guide for Python
+ Code" <http://www.python.org/dev/peps/pep-0008/>`_ For docstrings, we follow
+ `NumPy's "Docstring Standard"
+ <http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ and
+ `Python's "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.
+
+A useful trick for working on the source code is to build in-place so that there
+is no need to re-install after each change. 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 that 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.
diff --git a/content/download.txt b/content/download.txt
deleted file mode 100644
index 47a4a70..0000000
--- a/content/download.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-Download
-========
-
-Thank you for your interest in kwant. We expect to release it to the public in
-summer 2013. Please use the form below if you would like to get a notification
-once kwant is available. We will only use the provided email address to send
-the announcement.
-
-.. raw:: html
-
- <form action="/mail.php" method="POST">
- <p>Your name</p>
- <input type="text" name="name">
- <p>Your email address</p>
- <input type="text" name="email">
- <p>Optional comment</p>
- <textarea name="comment" rows="6" cols="40"></textarea>
- <br />
- <br />
- <input type="submit" value="Inform me once kwant is available">
- </form>
diff --git a/content/install.txt b/content/install.txt
new file mode 100644
index 0000000..24a2253
--- /dev/null
+++ b/content/install.txt
@@ -0,0 +1,227 @@
+Install
+=======
+
+Kwant can be installed either using some prepared packages (on GNU/Linux, Mac OS
+X, and Windows), or it can be built and installed from source.
+
+In general, installation from packages is advisable, especially for novice
+users. Expert users may find it helpful to build Kwant from source, as this
+will also allow them to customize Kwant to use certain optimized versions of
+libraries.
+
+Ubuntu (and derivatives)
+------------------------
+
+Execute the following commands::
+
+ sudo apt-add-repository ppa:kwant-project/ppa
+ sudo apt-get update
+ sudo apt-get install python-kwant
+
+This should provide Kwant for all the versions of Ubuntu >= 12.04.
+
+
+Debian GNU/Linux (and derivatives)
+----------------------------------
+
+The easiest way to install Kwant on a Debian system is using the pre-built
+packages we provide. Our packages are known to work with Debian "wheezy" and
+Debian "jessie", but they may also work on many other recent Debian-derived
+sytems as well. (For example the following works with recent Ubuntu
+installations as well.)
+
+The lines prefixed with ``sudo`` have to be run as root.
+
+1. Add the following lines to ``/etc/apt/sources.list``::
+
+ deb http://kwant-project.org/debian/ stable main
+ deb-src http://kwant-project.org/debian/ stable main
+
+2. (Optional) Add the OpenPGP key used to sign the repositories by executing::
+
+ sudo apt-key adv --keyserver pgp.mit.edu --recv-key C3F147F5980F3535
+
+ (Feel free to verify the validity of this key using the web of trust!)
+
+3. Update the package data, and install Kwant::
+
+ sudo apt-get update
+ sudo apt-get install python-kwant python-kwant-doc
+
+ The `python-kwant-doc` package is optional and installs the HTML
+ documentation of Kwant in the directory ``/usr/share/doc/python-kwant-doc``.
+
+
+Windows
+-------
+
+There are multiple distributions of scientific Python software for Windows that
+provide the prerequisites for Kwant. We recommend to use the packages kindly
+provided by Christoph Gohlke. To install Kwant on Windows
+
+1. Determine whether you have a 32-bit or 64-bit Windows installation by
+ following these `instructions <http://support.microsoft.com/kb/827218>`_.
+
+2. Download and install Python 2.7 for the appropriate architecture (32-bit or
+ 64-bit) from the official `Python download site
+ <http://www.python.org/download/>`_.
+
+3. Download and install ``scipy-stack``, ``tinyarray``, and ``kwant`` for Python
+ 2.7 from `Christoph Gohlke's page
+ <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_. Once again you should choose
+ the architecture that is appropriate for your system. ("win32" means 32-bit,
+ "amd64" means 64-bit -- even if you have a processor from Intel.) If the
+ download from Gohlke's site is slow, try to download from our `mirror
+ <http://downloads.kwant-project.org/gohlke-mirror/>`_.
+
+ You may see a warning that says "The publisher could not be verified. Do you
+ want to run this software?". Select "Run".
+
+
+Mac OSX
+-------
+
+There is a number of different package managers for bringing software
+from the Unix/Linux world to Mac OSX. Since the community is quite
+split, we provide Kwant and its dependencies both via the `MacPorts
+<http://www.macports.org>`_ and `homebrew <http://brew.sh>`_ systems.
+
+Mac OSX: MacPorts
+-----------------
+
+MacPorts is a full-fledged package manager that recreates a whole Linux-like
+environment on your Mac. It requires little choices to be made by the user,
+and allows for the simplest way to install Kwant.
+
+In order to install Kwant, you have to
+
+1. Install a recent version of MacPorts, as explained in the
+ `installation instructions of MacPorts
+ <http://www.macports.org/install.php>`_.
+ In particular, as explained there, you will have to install also a
+ few prerequisites, namely
+
+ * the Xcode developer tools (compiler suite for Mac OSX) from
+ `<http://developer.apple.com/downloads>`_. You need an Apple ID to
+ download: Note that if you have one already from using the App store
+ on the Mac/Ipad/Iphone/... you can use this one. You will also need the
+ command line tools: Within Xcode 4, you have to download them by going to
+ `Xcode->Preferences`, click on `Download`, go to `Components`,
+ select `Command Line Tools` and click on `Install`. Alternatively, you can
+ also directly download the command line tools from the
+ Apple developer website.
+ * if you have MacOSX 10.8 or higher, the X11 server from the
+ `XQuartz project <http://xquartz.macosforge.org>`_.
+
+2. After the installation, open a terminal and execute ::
+
+ echo http://downloads.kwant-project.org/macports/ports.tar |\
+ sudo tee -a /opt/local/etc/macports/sources.conf >/dev/null
+
+ (this adds the Kwant MacPorts download link
+ `<http://downloads.kwant-project.org/macports/ports.tar>`_ at the end of the
+ ``sources.conf`` file.)
+
+3. Execute ::
+
+ sudo port selfupdate
+
+4. Now, install Kwant and its prerequisites ::
+
+ sudo port install py27-kwant
+
+5. Finally, we choose python 2.7 to be the default python ::
+
+ sudo port select --set python python27
+
+ After that, you will need to close and reopen the terminal to
+ have all changes in effect.
+
+Notes:
+
+* If you have problems with macports because your institution's firewall
+ blocks macports (more precisely, the `rsync` port), resulting in
+ errors from ``sudo port selfupdate``, follow
+ `these instructions <https://trac.macports.org/wiki/howto/PortTreeTarball>`_.
+* Of course, if you already have macports installed, you can skip step 1
+ and continue with step 2.
+
+
+Mac OS X: homebrew
+------------------
+
+homebrew is a recent addition to the package managers on Mac OSX. It is
+more lightweight, tries to be as minimalistic as possible and give the user
+more freedom. Because of that, it requires a little more experience on
+the user side compared to MacPorts. The requirements are moderate though,
+if you know how to add directories to the ``$PATH`` variable for your shell,
+you are safe.
+
+1. Open a terminal and install homebrew as described on the `homebrew
+ homepage <http://brew.sh>`_ (instructions are towards the end of
+ the page)
+
+2. Run ::
+
+ brew doctor
+
+ and follow its directions. It will ask for a few prerequisites to be
+ installed, in particular
+
+ * the Xcode developer tools (compiler suite for Mac OSX) from
+ `<http://developer.apple.com/downloads>`_. You need an Apple ID to
+ download: Note that if you have one already from using the App store
+ on the Mac/Ipad/Iphone/... you can use this one. Note that downloading
+ the command line tools (not the full Xcode suite) suffices. If you have
+ the full Xcode suite installed, you might need to download the command
+ line tools manually if you have version 4 or higher. In this case
+ go to `Xcode->Preferences`, click on `Download`, go to `Components`,
+ select `Command Line Tools` and click on `Install`.
+ * although `brew doctor` might not complain about it right away,
+ while we're at it, you should also install the X11 server from the
+ `XQuartz project <http://xquartz.macosforge.org>`_ if you have Mac
+ OSX 10.8 or higher.
+
+3. Add permanently ``/usr/local/bin`` before ``/usr/bin/`` in the ``$PATH$``
+ environment variable of your shell, for example by adding ::
+
+ export PATH=/usr/local/bin:$PATH
+
+ at the end of your ``.bash_profile`` or ``.profile``. Then close
+ the terminal Terminal and reopen it again.
+
+4. Install a few prerequisites ::
+
+ brew install gfortran python
+
+5. Add additional repositories ::
+
+ brew tap homebrew/science
+ brew tap samueljohn/python
+ brew tap michaelwimmer/kwant
+
+6. Install Kwant and its prerequisites ::
+
+ pip install nose
+ brew install numpy scipy matplotlib
+ brew install kwant
+
+Notes:
+
+- If something does not work as expected, use ``brew doctor`` for
+ instructions (it will find conflicts and things like that).
+- As mentioned, homebrew allows for quite some freedom. In particular,
+ if you are an expert, you don't need necessarily to install
+ numpy/scipy/matplotlib from homebrew, but can use your own installation.
+ The only prerequisite is that they are importable from python. (the
+ Kwant installation will in any case complain if they are not)
+- In principle, you need not install the homebrew python, but could use
+ Apple's already installed python. Homebrew's python is more up-to-date,
+ though.
+
+
+Building and installing from source
+-----------------------------------
+
+See complete `building instructions
+</docs/build/html/pre/install.html#building-and-installing-from-source>`_.
diff --git a/templates/base.mako b/templates/base.mako
index f64048d..3ce526f 100644
--- a/templates/base.mako
+++ b/templates/base.mako
@@ -17,10 +17,11 @@
<h3 class="hidden_structure">Navigation</h3>
<ul class="navigation">
<li><a href="/">home</a></li>
+ <li><a href="/install.html">install</a></li>
<li><a href="/docs/">documentation</a></li>
- <li><a href="/download.html">download</a></li>
- <li><a href="/contact.html">contact</a></li>
<li><a href="/citing.html">citing</a></li>
+ <li><a href="/contribute.html">contribute</a></li>
+ <li><a href="/contact.html">contact</a></li>
</ul>
</div>
--
GitLab