Commit 2db90fdf authored by Joseph Weston's avatar Joseph Weston

Merge branch 'stable-1.2'

parents 590bf914 f6746df0
Pipeline #23948 passed with stage
in 2 minutes and 56 seconds
......@@ -6,10 +6,24 @@ image: quantumtinkerer/research
## Documentation for the format of this file can be found here:
## https://docs.gitlab.com/ce/ci/yaml/README.html#configuration-of-your-builds-with-gitlab-ci-yml
run tests:
test minimal requirements:
script:
- conda install -y -q pytest-cov
- conda env create -f environment-minimal.yml
- source activate qsymm-minimal
- py.test qsymm/ --cov=qsymm --verbose --cov-report html --cov-report term
artifacts:
paths:
- htmlcov
stage: test
test latest requirements:
script:
- conda env create -f environment-latest.yml
- source activate qsymm-latest
- py.test qsymm/ --cov=qsymm --verbose --cov-report html --cov-report term
artifacts:
paths:
- htmlcov
reports:
junit: tests.xml
stage: test
......@@ -5,6 +5,7 @@ Below is a list of the contributors to Qsymm:
+ Tomas Rosdahl
+ Rafal Skolasinski
+ Daniel Varjas
+ [Joseph Weston](https://weston.cloud)
For a full list of contributors run
......
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [unreleased]
## [1.2.5] - 2019-11-11
### Added
- Added basic reference documentation
- Added citation instructions in CITING.md
- Added a tutorial with downloadable Python files and Jupyter notebooks
### Fixed
- Allow 'display_family' to work when IPython is not installed
- Bug when multiplying a model by a sympy expression (undefined variable)
- Bug when multiplying BlochCoeff with sympy expression (sympy multiplication was
being used, when BlochCoeff multiplication should have been used)
- Remove copying of Sympy symbols (the hash values for the original and copy is
different in some cases (probably a bug in Sympy)), which broke comparison
between Models.
- Remove 'real' assumption from Sympy symbols in 'hamiltonian_from_family'; this
makes all Sympy symbols in Qsymm consistently have no assumptions.
- Minor clarifications to various docstrings
### Removed
- Removed the notebooks from the source repository
## [1.2.4] - 2019-10-17
### Fixed
- Set correct content-type on long description metadata
## [1.2.3] - 2019-10-17
### Fixed
- Add long description to package metadata
## [1.2.2] - 2019-10-17
### Fixed
- Adding zero to a model is now idempotent
## [1.2.1] - 2019-09-02
### Added
- Add CHANGELOG.md
### Fixed
+ Restore compatibility with Python 3.5
## [1.2.0] - 2019-08-30
### Added
- Factory functions for discrete symmetries: `time_reversal`, `particle_hole`, `chiral`, `inversion`, `rotation`, `mirror`.
- Better representation of `PointGroupElement`s and `ContinuousGroupGenerator`, using `_repr_pretty_` and `_repr_latex_`. Remove `print_PG_elements` and update example notebooks.
- Implemented new functionality in `Model`:
+ Implement `__matmul__` (`@`).
+ Support of sparse matrices and `LinearOperator` as values.
+ Consistent support of scalar valued `Model`s.
+ Add `keep` to only keep track of certain symbolic coefficients.
+ More options and more transparent initialization, allow string keys which are automatically symmpified by default.
+ Several new utility functions, such as `trace`, `reshape`, `allclose` etc.
### Changed
- Slight change to the internal representation of `PointGroupElements`, allow mixing integer tinyarray with either sympy matrix or floating point tinyarray in the rotation part, but do not allow mixing the latter two representations. This removes the need to have two different representations for simple operators. Optimize multiplication by caching.
- Changes in the API of `Model`:
- Add `format` attribute to keep track of the type of data entries (i.e scalar, dense or sparse array).
- Change the behaviour of `*` for `Model` objects, matrix multiplication only works with `@` from now on. This breaks backward compatibility, a few uses in the qsymm code base were fixed.
- Stop supporting a sequence of ints as `momenta`, instead string keys (e.g. `'k_x'`) or `sympy` expressions can be used. Certain other, rarely used ways to initialize `Model` don't work anymore, some tests were changed accordingly.
- Stop rounding and removing small entries from `Model` objects. This means that testing that the `Model` is empty is not a good test anymore to see if it is approximately zero. Use `Model.allclose` instead.
- Optimizations in `Model`:
+ Remove unnecessary deep copying, which was slow.
+ Optimize the implementation of arithmetic operations to minimize number of loops and function calls.
+ Fast initialization by making restructuring optional when initialized with a dict.
+ Clean up the code of `BlochModel` to utilize improvements in `Model`.
+ Update symmetry finder to work with sparse models.
### Deprecated
- Deprecate initializing empty `Model` without providing `shape` and `format`.
## [1.1.0] - 2018-12-05
Many of these changes were made in anticipation of integrating `qsymm` with `kwant`,
allowing conversion between the Hamiltonian formats used.
### Added
+ `BlochModel` as a subclass of `Model` in order to store Bloch Hamiltonians
with floating point hopping vectors.
+ `bravais_point_group` to find the point group of a Bravais lattice using the
translation vectors only. This is intended for generating candidades for `symmetries`.
### Changed
+ Change the way equality of `Model`s is tested, the current implementation treats
tolerances more consistently, this fixes some bugs in symmetry finding.
+ Allow using floating point rotation matrices in `PointGroupElement`.
### Fixed
+ Several bugs and internal code restructuring.
# Citing Qsymm
We provide Qsymm as free software under a [BSD license](LICENSE).
If you have used Qsymm for work that has lead to a scientific publication, please
mention the fact that you used it explicitly in the text body.
In addition we ask you to cite the [Qsymm paper](https://doi.org/10.1088/1367-2630/aadf67):
Dániel Varjas, Tómas Ö Rosdahl, and Anton R Akhmerov
Qsymm: algorithmic symmetry finding and symmetric Hamiltonian generation
New J. Phys. 20 093026 (2018)
include LICENSE
include AUTHORS.md
include CHANGELOG.md
include CITING.md
# Qsymm
[![Install with pip](https://img.shields.io/pypi/v/qsymm.svg)](https://pypi.python.org/pypi/qsymm)
[![install wtih conda](https://img.shields.io/badge/install%20with-conda-green.svg)](https://anaconda.org/conda-forge/qsymm)
[![pipeline status](https://gitlab.kwant-project.org/qt/qsymm/badges/master/pipeline.svg)](https://gitlab.kwant-project.org/qt/qsymm/commits/master)
[![coverage report](https://gitlab.kwant-project.org/qt/qsymm/badges/master/coverage.svg)](https://gitlab.kwant-project.org/qt/qsymm/commits/master)
[![docs status](https://readthedocs.org/projects/pip/badge/?version=latest&style=flat)](https://qsymm.readthedocs.io/en/latest/)
**Symmetry finder and symmetric Hamiltonian generator**
`qsymm` is an [open-source](LICENSE) Python library that makes symmetry analysis simple.
It automatically generates model Hamiltonians from symmetry constraints and finds the full symmetry group of your Hamiltonian.
It automatically generates model Hamiltonians from symmetry constraints
and finds the full symmetry group of your Hamiltonian.
Check out the introductory [example notebook](basics.ipynb) to see examples of how to use `qsymm`.
Check out the [introductory tutorial][basic_tutorial] to see examples of how to use `qsymm`.
## Implemented algorithms
![summary of methods](summary.svg "Summary of methods")
The two core concepts in `qsymm` are _Hamiltonian families_ (Hamiltonians that may depend on free parameters) and _symmetries_. We provide powerful classes to handle these:
The two core concepts in `qsymm` are _Hamiltonian families_ (Hamiltonians that may depend on
free parameters) and _symmetries_. We provide powerful classes to handle these:
+ `Model` is used to store symbolic Hamiltonians that may depend on momenta and other free parameters. We use `sympy` for symbolic manipulation, but our implementation utilizes `numpy` arrays for efficient calculations with matrix valued functions.
+ `Model` is used to store symbolic Hamiltonians that may depend on momenta and other free parameters.
We use `sympy` for symbolic manipulation, but our implementation utilizes `numpy` arrays for
efficient calculations with matrix valued functions.
+ `PointGroupElement` and `ContinuousGroupGenerator` are used to store symmetry operators. Besides the ability to combine symmetries, they can also be applied to a `Model` to transform it.
+ `PointGroupElement` and `ContinuousGroupGenerator` are used to store symmetry operators.
Besides the ability to combine symmetries, they can also be applied to a `Model` to transform it.
We implement algorithms that form a two-way connection between Hamiltonian families and symmetries.
+ Symmetry finding is handled by `symmetries`, it takes a `Model` as input and finds all of its symmetries, including conserved quantities, time reversal, particle-hole, and spatial rotation symmetries. See [`symmetry_finder.ipynb`](symmetry_finder.ipynb) and [`kekule.ipynb`](kekule.ipynb) for detailed examples.
+ Symmetry finding is handled by `symmetries`, it takes a `Model` as input and finds all of its symmetries,
including conserved quantities, time reversal, particle-hole, and spatial rotation symmetries.
See the [symmetry finder tutorial][symmetry_finder_tutorial] and the
[kekule tutorial][kekule_tutorial] for detailed examples.
+ `continuum_hamiltonian` and `bloch_family` are used to generate __k.p__ or lattice Hamiltonians from symmetry constraints. See [`kdotp_generator.ipynb`](kdotp_generator.ipynb), [`bloch_generator.ipynb`](bloch_generator.ipynb) and [`kekule.ipynb`](kekule.ipynb) for detailed examples.
+ `continuum_hamiltonian` and `bloch_family` are used to generate __k.p__ or lattice Hamiltonians
from symmetry constraints. See the [k-dot-p generator tutorial][kdotp_generator_tutorial],
the [Bloch generator tutorial][bloch_generator_tutorial] and the
[kekule tutorial][kekule_tutorial] for detailed examples.
## Installation
`qsymm` works with Python 3.5 and is available on PyPI:
......@@ -32,5 +48,19 @@ pip install qsymm
Some of the example notebooks also require [Kwant](https://kwant-project.org/).
## Documentation
Qsymm's documentation is hosted on [Read the Docs](https://qsymm.readthedocs.io/en/latest/)
## Citing
Check out [CITING.md](CITING.md) for instructions on how to cite Qsymm in your publications.
## Development
`qsymm` is on [Gitlab](https://gitlab.kwant-project.org/qt/qsymm), visit there if you would like to to contribute, report issues, or get the latest development version.
`qsymm` is on [Gitlab](https://gitlab.kwant-project.org/qt/qsymm), visit there if you would
like to to contribute, report issues, or get the latest development version.
[basic_tutorial]: https://qsymm.readthedocs.io/en/latest/tutorial/basics.html
[symmetry_finder_tutorial]: https://qsymm.readthedocs.io/en/latest/tutorial/symmetry_finder.html
[bloch_generator_tutorial]: https://qsymm.readthedocs.io/en/latest/tutorial/bloch_generator.html
[kdotp_generator_tutorial]: https://qsymm.readthedocs.io/en/latest/tutorial/kdotp_generator.html
[kekule_tutorial]: https://qsymm.readthedocs.io/en/latest/tutorial/kekule.html
......@@ -2,6 +2,22 @@
## Ensure that all tests pass
## Update the changelog
Change the top `unreleased` line to the new version number and add the date, e.g.
```
## [1.2.5] - 2019-11-11
```
Add a new `unreleased` line to the top of the changelog, e.g.
```
## [unreleased]
## [1.2.5] - 2019-11-11
```
## Tag the release
Make an **annotated** tag for the release. The tag must be the version number prefixed by the letter 'v':
......@@ -48,3 +64,11 @@ git push origin v<version> v<version+1>-dev
twine upload dist/*
```
### Create conda-forge package
Some time (typically minutes/hours) after making the PyPI release a pull
request will automatically be opened on the
[Qsymm feedstock](https://github.com/conda-forge/qsymm-feedstock/) repository.
This pull request should be checked to make sure the tests pass and can then
be merged. This will make a new release of the Qsymm conda package on conda-forge.
This diff is collapsed.
This diff is collapsed.
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [1.1.0] -- 2018-12-05
Many of these changes were made in anticipation of integrating `qsymm` with `kwant`,
allowing conversion between the Hamiltonian formats used.
### Added
+ `BlochModel` as a subclass of `Model` in order to store Bloch Hamiltonians
with floating point hopping vectors.
+ `bravais_point_group` to find the point group of a Bravais lattice using the
translation vectors only. This is intended for generating candidades for `symmetries`.
### Changed
+ Change the way equality of `Model`s is tested, the current implementation treats
tolerances more consistently, this fixes some bugs in symmetry finding.
+ Allow using floating point rotation matrices in `PointGroupElement`.
### Fixed
+ Several bugs and internal code restructuring.
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
name: qsymm
channels:
- conda-forge
dependencies:
- python=3.7
- numpy
- scipy
- sympy
- tinyarray
## Dev Dependencies
# Testing
- pytest
- pytest-cov
- pytest-flakes
- pytest-pep8
## Doc Dependencies
- sphinx
- jupyter_sphinx
- sphinx_rtd_theme
- m2r
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd
../../CHANGELOG.md
\ No newline at end of file
../../CITING.md
\ No newline at end of file
../../LICENSE
\ No newline at end of file
../../basics.ipynb
\ No newline at end of file
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
package_path = os.path.abspath("../..")
# Insert into sys.path so that we can import qsymm here
sys.path.insert(0, package_path)
import qsymm # noqa: E402
# Insert into PYTHONPATH so that jupyter-sphinx will pick it up
os.environ["PYTHONPATH"] = ":".join((package_path, os.environ.get("PYTHONPATH", "")))
# -- Project information -----------------------------------------------------
project = 'Qsymm'
copyright = '2019, Qsymm Authors'
author = 'Qsymm Authors'
version = qsymm.__version__
release = qsymm.__version__
# -- 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.
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.autosectionlabel",
"sphinx.ext.intersphinx",
"sphinx.ext.mathjax",
"sphinx.ext.viewcode",
"sphinx.ext.napoleon",
"jupyter_sphinx.execute",
"m2r",
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# text in backticks should be treated as references to the API documentation
default_role = "autolink"
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# The license file has no extension, so Sphinx ignores it by default, so we
# must add it here
html_extra_path = ['LICENSE']
# -- Extension config
autosummary_generate = True
.. Qsymm documentation master file, created by
sphinx-quickstart on Sat Oct 19 10:01:20 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
.. mdinclude:: ../../README.md
.. toctree::
:maxdepth: 2
:hidden:
:caption: Contents:
CITING
CHANGELOG
tutorial/tutorial
reference/qsymm
qsymm.groups module
===================
.. automodule:: qsymm.groups
:members:
:undoc-members:
:show-inheritance:
qsymm.hamiltonian\_generator module
===================================
.. automodule:: qsymm.hamiltonian_generator
:members:
:undoc-members:
:show-inheritance:
qsymm.linalg module
===================
.. automodule:: qsymm.linalg
:members:
:undoc-members:
:show-inheritance:
qsymm.model module
==================
.. automodule:: qsymm.model
:members:
:undoc-members:
:show-inheritance:
Qsymm Reference Documentation
=============================
Submodules
----------
.. toctree::
qsymm.model
qsymm.symmetry_finder
qsymm.hamiltonian_generator
qsymm.groups
qsymm.linalg
qsymm.symmetry\_finder module
=============================
.. automodule:: qsymm.symmetry_finder
:members:
:undoc-members:
:show-inheritance:
../../summary.svg
\ No newline at end of file
.. _tutorial_basics:
Qsymm Basics
============
.. seealso::
The complete source code of this example can be found in :jupyter-download:script:`basics`.
A Jupyter notebook can be found in :jupyter-download:notebook:`basics`.
.. jupyter-kernel::
:id: basics
Getting started with Qsymm is as simple as importing it:
.. jupyter-execute::
import qsymm
To make effective use of Qsymm we'll also need a few other utilities: ``numpy``
handling numeric arrays, and ``sympy`` for symbolic mathematics:
.. jupyter-execute::
import numpy as np
import sympy
In all the following tutorials we will use these standard imports, and they won't
be explicitly shown
Defining a Qsymm model
----------------------
Let's start by defining a 3D Rashba Hamiltonian symbolically as a Python string:
.. jupyter-execute::
ham = ("hbar^2 / (2 * m) * (k_x**2 + k_y**2 + k_z**2) * eye(2) +" +
"alpha * sigma_x * k_x + alpha * sigma_y * k_y + alpha * sigma_z * k_z")
We can then create a Qsymm `~qsymm.model.Model` directly from this symbolic Hamiltonian:
.. jupyter-execute::
H = qsymm.Model(ham)
We can then directly inspect the contents by printing the `~qsymm.model.Model`:
.. jupyter-execute::
print(H)
We can also extract a more readable representation by using the ``tosympy`` method, which
converts the `~qsymm.model.Model` to a ``sympy`` expression:
.. jupyter-execute::
H.tosympy(nsimplify=True)
The argument ``nsimplify=True`` makes the output more readable by forcing ``sympy`` to elide
factors of ``1.0`` that multiply each term. Note that Qsymm automatically interprets the symbols
``sigma_x``, ``sigma_y`` and ``sigma_z`` as the Pauli matrices, and ``eye(2)`` as the 2x2
identity matrix.
`~qsymm.model.Model` as a ``momenta`` attribute that specifies which symbols are considered the
momentum variables:
.. jupyter-execute::
H.momenta
By default Qsymm assumes that your model is written in 3D (even if it does not include all 3
momenta). To define a lower-dimensional model you must explicitly specify the momentum
variables, e.g:
.. jupyter-execute::
ham2D = ("hbar^2 / (2 * m) * (k_x**2 + k_z**2) * eye(2) +" +
"alpha * sigma_x * k_x + alpha * sigma_y * k_z")
H2D = qsymm.Model(ham2D, momenta=['k_x', 'k_z'])
.. jupyter-execute::
H2D.tosympy(nsimplify=True)
.. jupyter-execute::
H2D.momenta
Defining group elements
-----------------------
Qsymm is all about finding and generating symmetries of models, so it is unsurprising
that it contains utilities for defining group elements.
Below are a few examples of the sorts of things you can define with Qsymm:
.. jupyter-execute::
# Identity in 3D
E = qsymm.identity(3)
# Inversion in 3D
I = qsymm.inversion(3)
# 4-fold rotation around the x-axis
C4 = qsymm.rotation(1/4, [1, 0, 0])
# 3-fold rotation around the [1, 1, 1] axis
C3 = qsymm.rotation(1/3, [1, 1, 1])
# Time reversal
TR = qsymm.time_reversal(3)
# Particle-hole
PH = qsymm.particle_hole(3)
The documentation page of the `qsymm.groups` module contains an exhaustive list
of what can be generated.
As with other Qsymm objects we can get a readable representation of these
group elements:
.. jupyter-execute::
C4
.. jupyter-execute::
TR
Given a set of group generators we can also generate a group:
.. jupyter-execute::
cubic_gens = {I, C4, C3, TR, PH}
cubic_group = qsymm.groups.generate_group(cubic_gens)
print(len(cubic_group))
Group elements can be multiplied and inverted, as we would expect:
.. jupyter-execute::
C3 * C4
.. jupyter-execute::
C3**-1
We can also apply group elements to the `~qsymm.model.Model` that we defined
in the previous section:
.. jupyter-execute::
H_with_TR = TR.apply(H)
H_with_TR.tosympy(nsimplify=True)
Defining continuous group generators
------------------------------------
In addition to the group elements we can also define generators of continuous groups
using `qsymm.groups.ContinuousGroupGenerator`:
.. jupyter-execute::
sz = qsymm.ContinuousGroupGenerator(None, np.array([[1, 0], [0, -1]]))
The first argument to `~qsymm.groups.ContinuousGroupGenerator` is the realspace rotation generator;
by specifying ``None`` we indicate that we want the rotation part to be zero. The second
argument is the unitary action of the generator on the Hilbert space as a Hermitian matrix.
Applying a `~qsymm.groups.ContinuousGroupGenerator` to a `~qsymm.model.Model` calculates the commutator: