README.rst 4.54 KB
Newer Older
Kloss's avatar
Kloss committed
1 2
About kwantSpectrum
===================
Kloss's avatar
Kloss committed
3

Kloss's avatar
Kloss committed
4
kwantSpectrum is an extension to `Kwant <http://kwant-project.org/>`__ that
Christoph Groth's avatar
Christoph Groth committed
5 6 7 8 9
adaptively analyzes band structures of infinite quasi-1d systems.  The
bandstructure is approximated to an arbitrary precision by piecewise cubic
polynomials.  Functionality to deal with special points, intervals, and the
periodic nature of the spectrum is provided.

Kloss's avatar
Kloss committed
10

Kloss's avatar
Kloss committed
11
kwantSpectrum is distributed under the `2-clause BSD license <https://gitlab.kwant-project.org/kwant/kwantspectrum/-/blob/master/LICENSE.rst>`_
Kloss's avatar
Kloss committed
12

Kloss's avatar
Kloss committed
13
Website: https://kwant-project.org/extensions/kwantspectrum
Kloss's avatar
Kloss committed
14

Kloss's avatar
Kloss committed
15
Source code: https://gitlab.kwant-project.org/kwant/kwantspectrum
Kloss's avatar
Kloss committed
16

17
Conda package: https://github.com/conda-forge/kwantspectrum-feedstock
Kloss's avatar
Kloss committed
18 19 20 21 22


Installation
############

23 24 25
kwantSpectrum packages are hosted on PyPI and conda.
The installation should work GNU/Linux system as Debian and Ubuntu,
as well as on MacOS and Windows.
Kloss's avatar
Kloss committed
26

27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51
**PyPI**::

    python3 -m pip install --user kwantspectrum

**conda**::

    conda install -c conda-forge kwantspectrum


Installation from source
^^^^^^^^^^^^^^^^^^^^^^^^

kwantSpectrum can be installed directly from the source code repository::

    python3 -m pip install --user git+https://gitlab.kwant-project.org/kwant/kwantspectrum.git

For development, kwantSpectrum can be cloned from the official repository with::

    git clone https://gitlab.kwant-project.org/kwant/kwantspectrum.git

The requirements listed below must be installed by hand.


Build requirements
------------------
Kloss's avatar
Kloss committed
52

Kloss's avatar
Kloss committed
53
kwantSpectrum has following non-Python dependency:
Kloss's avatar
Kloss committed
54 55 56

- `Kwant <https://kwant-project.org/>`__

Kloss's avatar
Kloss committed
57
Kwant can be installed with the following command::
Kloss's avatar
Kloss committed
58 59 60 61 62

   sudo apt-add-repository -s ppa:kwant-project/ppa
   sudo apt-get update
   sudo apt-get install python3-kwant

Kloss's avatar
Kloss committed
63 64
kwantSpectrum requires at least Python 3.5. The following packages must
be installed to build kwantSpectrum:
Kloss's avatar
Kloss committed
65 66 67 68

- `NumPy <https://numpy.org/>`_
- `SciPy <https://www.scipy.org/>`_

69
The packages can be installed by the standard *pip* command::
Kloss's avatar
Kloss committed
70

71
    python3 -m pip install --user numpy scipy
Kloss's avatar
Kloss committed
72 73 74

Testing requirements
--------------------
Kloss's avatar
Kloss committed
75
The kwantSpectrum test suite requires the following Python packages:
Kloss's avatar
Kloss committed
76 77 78 79 80 81 82 83

- `pytest <https://docs.pytest.org/en/latest/>`_
- `pytest-cov <https://pytest-cov.readthedocs.io/en/latest/>`_
- `pytest-flake8 <https://pypi.org/project/pytest-flake8/>`_


The packages can be installed by the standard *pip* command::

84
    python3 -m pip install --user pytest pytest-cov pytest-flake8
Kloss's avatar
Kloss committed
85 86 87

Documentation requirements
--------------------------
Kloss's avatar
Kloss committed
88
Building the documentation requires the following Python packages:
Kloss's avatar
Kloss committed
89

Kloss's avatar
Kloss committed
90
- `matplotlib <https://matplotlib.org/>`_
Kloss's avatar
Kloss committed
91 92 93 94 95 96
- `sphinx <https://www.sphinx-doc.org/en/master/>`_
- `jupyter-sphinx <https://jupyter-sphinx.readthedocs.io/en/latest/>`_


The packages can be installed by the standard *pip* command::

97
    python3 -m pip install --user matplotlib sphinx jupyter-sphinx
Kloss's avatar
Kloss committed
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124


Test suite
----------

Unittests can be run directly in the local source repository from the command line::

    pytest


Building the documentation
--------------------------

The documentation can be build directly in the ``/doc`` folder of the 
local source repository from the command line::

    make html

The generated html documentation can be browsed
by opening the file ``doc/build/html/index.html`` with a web browser.


Documentation
#############

Full documentation including a tutorial:

Kloss's avatar
Kloss committed
125 126 127 128 129 130 131 132 133 134 135 136 137 138
- https://kwant-project.org/extensions/kwantspectrum

Communication
#############

The kwant-discuss mailing list is the main communication channel for
questions and discussions around kwantSpectrum. Searching and using the mailing list
is explained in section
`mailing list <https://kwant-project.org/community#mailing-list>`_.

- Mailing list: kwant-discuss@kwant-project.org

In addition, the authors can be reached by email, see below.

Kloss's avatar
Kloss committed
139 140 141 142 143 144 145 146 147 148 149 150 151 152 153


Contributing
############

Contributions and feedback are always welcome. 
Report bugs and follow development through the project repository.
Authors can be reached by email
or a merge request may be opened on the project's website.
Please make sure that the test suite runs without errors before opening
a new merge request.

License
#######

Kloss's avatar
Kloss committed
154 155
kwantSpectrum is distributed under BSD license, see the file ``LICENSE.rst``
in the project repository.
Kloss's avatar
Kloss committed
156 157 158 159 160


Authors
#######

Kloss's avatar
Kloss committed
161
The principle developer of kwantSpectrum is:
Kloss's avatar
Kloss committed
162

Kloss's avatar
Kloss committed
163
* Thomas Kloss (CEA Grenoble), kloss@itp.uni-frankfurt.de
Kloss's avatar
Kloss committed
164 165 166 167 168 169

Contributors to the project are:

* Christoph Groth (CEA Grenoble)
* Xavier Waintal (CEA Grenoble)
* Benoît Rossignol (CEA Grenoble)
170
* Bas Nijholt (Microsoft)
Kloss's avatar
Kloss committed
171 172

(CEA = Commissariat à l'énergie atomique et aux énergies alternatives)