From b4e17523f2fdc448782a820430f267647f0d832a Mon Sep 17 00:00:00 2001 From: Giovanni Pizzi Date: Sun, 17 May 2020 12:34:28 +0200 Subject: [PATCH] Docs were lost in the v1 -> v2 migration... --- docs/.gitignore | 1 + docs/Makefile | 39 ++++ docs/requirements_for_rtd.txt | 1 + docs/source/conf.py | 348 +++++++++++++++++++++++++++++ docs/source/index.rst | 27 +++ docs/source/maindoc.rst | 131 +++++++++++ docs/source/module_guide/index.rst | 30 +++ 7 files changed, 577 insertions(+) create mode 100644 docs/.gitignore create mode 100755 docs/Makefile create mode 100644 docs/requirements_for_rtd.txt create mode 100755 docs/source/conf.py create mode 100755 docs/source/index.rst create mode 100644 docs/source/maindoc.rst create mode 100644 docs/source/module_guide/index.rst diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..d163863 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +build/ \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100755 index 0000000..c93f2fe --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,39 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -n -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: all help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext customdefault + +customdefault: + $(SPHINXBUILD) -b html -nW $(ALLSPHINXOPTS) $(BUILDDIR)/html + +all: html + +clean: + rm -r $(BUILDDIR) + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + + +view: + xdg-open $(BUILDDIR)/html/index.html diff --git a/docs/requirements_for_rtd.txt b/docs/requirements_for_rtd.txt new file mode 100644 index 0000000..d170e1a --- /dev/null +++ b/docs/requirements_for_rtd.txt @@ -0,0 +1 @@ +setuptools>41 diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100755 index 0000000..ce0fc60 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,348 @@ +# -*- coding: utf-8 -*- +# pylint:disable=redefined-builtin +import os +import time + +# 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 seekpath + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# needs_sphinx = '1.0' + +# 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.mathjax", + # 'sphinx.ext.intersphinx', + "sphinx.ext.viewcode", +] + +intersphinx_mapping = { + # 'python': ('https://docs.python.org/2.7', None), +} + +nitpick_ignore = [("py:obj", "module")] + +# 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-sig' + +# The master toctree document. +# ~ master_doc = 'index' +master_doc = "index" + +# General information about the project. +project = u"seekpath" +copyright = ( + u"2016-{}, Giovanni Pizzi, ECOLE POLYTECHNIQUE FEDERALE DE LAUSANNE (Theory and Simulation of Materials (THEOS) " + "and National Centre for Computational Design and Discovery of Novel Materials (NCCR MARVEL)),Switzerland. " + "All rights reserved.".format(time.localtime().tm_year) +) + +# 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 short X.Y version. +version = ".".join(seekpath.__version__.split(".")[:2]) +# The full version, including alpha/beta/rc tags. +release = seekpath.__version__ + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ["doc.rst"] +# ~ exclude_patterns = ['index.rst'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +show_authors = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# -- 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 = 'basicstrap' +## SET BELOW + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# ~ html_theme_options = { +# ~ 'inner_theme': True, +# ~ 'inner_theme_name': 'bootswatch-darkly', +# ~ 'nav_fixed_top': False +# ~ } + +# Add any paths that contain custom themes here, relative to this directory. +# ~ html_theme_path = ["."] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +# html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# html_logo = "images/.png" + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# html_favicon = "images/favicon.ico" + +# 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'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +# html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {} + +# If false, no module index is generated. +# html_domain_indices = True + +# If false, no index is generated. +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# ~ html_show_copyright = False + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +html_use_opensearch = "http://seekpath.readthedocs.io" + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +html_search_language = "en" + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = "seekpathdoc" + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + #'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + #'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + #'preamble': '', + # Latex figure (float) alignment + #'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +# latex_documents = [ +# ] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# If true, show page references after internal links. +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +# latex_domain_indices = True + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +# man_pages = [ +# ] + +# If true, show URL addresses after external links. +# man_show_urls = False + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +# texinfo_documents = [ +# ] + +# Documents to append as an appendix to all manuals. +# texinfo_appendices = [] + +# If false, no module index is generated. +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# texinfo_no_detailmenu = False + +# NOTE: it is needed to have these lines before load_dbenv() +on_rtd = os.environ.get("READTHEDOCS", None) == "True" + +if not on_rtd: # only import and set the theme if we're building docs locally + try: + import sphinx_rtd_theme + + html_theme = "sphinx_rtd_theme" + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + except ImportError: + # No sphinx_rtd_theme installed + pass + +# Warnings to ignore when using the -n (nitpicky) option +# We should ignore any python built-in exception, for instance +nitpick_ignore = [ + ("py:exc", "ArithmeticError"), + ("py:exc", "AssertionError"), + ("py:exc", "AttributeError"), + ("py:exc", "BaseException"), + ("py:exc", "BufferError"), + ("py:exc", "DeprecationWarning"), + ("py:exc", "EOFError"), + ("py:exc", "EnvironmentError"), + ("py:exc", "Exception"), + ("py:exc", "FloatingPointError"), + ("py:exc", "FutureWarning"), + ("py:exc", "GeneratorExit"), + ("py:exc", "IOError"), + ("py:exc", "ImportError"), + ("py:exc", "ImportWarning"), + ("py:exc", "IndentationError"), + ("py:exc", "IndexError"), + ("py:exc", "KeyError"), + ("py:exc", "KeyboardInterrupt"), + ("py:exc", "LookupError"), + ("py:exc", "MemoryError"), + ("py:exc", "NameError"), + ("py:exc", "NotImplementedError"), + ("py:exc", "OSError"), + ("py:exc", "OverflowError"), + ("py:exc", "PendingDeprecationWarning"), + ("py:exc", "ReferenceError"), + ("py:exc", "RuntimeError"), + ("py:exc", "RuntimeWarning"), + ("py:exc", "StandardError"), + ("py:exc", "StopIteration"), + ("py:exc", "SyntaxError"), + ("py:exc", "SyntaxWarning"), + ("py:exc", "SystemError"), + ("py:exc", "SystemExit"), + ("py:exc", "TabError"), + ("py:exc", "TypeError"), + ("py:exc", "UnboundLocalError"), + ("py:exc", "UnicodeDecodeError"), + ("py:exc", "UnicodeEncodeError"), + ("py:exc", "UnicodeError"), + ("py:exc", "UnicodeTranslateError"), + ("py:exc", "UnicodeWarning"), + ("py:exc", "UserWarning"), + ("py:exc", "VMSError"), + ("py:exc", "ValueError"), + ("py:exc", "Warning"), + ("py:exc", "WindowsError"), + ("py:exc", "ZeroDivisionError"), + ("py:obj", "str"), + ("py:obj", "list"), + ("py:obj", "tuple"), + ("py:obj", "int"), + ("py:obj", "float"), + ("py:obj", "bool"), + ("py:obj", "Mapping"), +] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100755 index 0000000..c3a6ad6 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,27 @@ +########### +`SeeK-path` +########### + +.. _GitHub: http://github.com/giovannipizzi/seekpath + + +.. toctree:: + :maxdepth: 4 + + maindoc + +Python modules documentation +============================ + +.. toctree:: + :maxdepth: 4 + + module_guide/index + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/source/maindoc.rst b/docs/source/maindoc.rst new file mode 100644 index 0000000..b728d8e --- /dev/null +++ b/docs/source/maindoc.rst @@ -0,0 +1,131 @@ +Welcome to documentation of SeeK-path +===================================== + +``SeeK-path`` is a python module to obtain and visualize band paths in the +Brillouin zone of crystal structures. + +The definition of k-point labels follows crystallographic convention, as defined +and discussed in the `HPKOT paper`_. Moreover, the Bravais lattice is detected +properly using the spacegroup symmetry. Also the suggested band path provided +in the `HPKOT paper`_ is returned. +Systems without time-reversal and inversion-symmetry are also properly +taken into account. + + +=========== +How to cite +=========== +If you use this tool, please cite the following work: + +- Y. Hinuma, G. Pizzi, Y. Kumagai, F. Oba, I. Tanaka, *Band structure diagram + paths based on crystallography*, Comp. Mat. Sci. 128, 140 (2017) + (`JOURNAL LINK`_, `arXiv link`_). +- You should also cite `spglib`_ that is an essential library used in the + implementation: A. Togo, I. Tanaka, + "Spglib: a software library for crystal symmetry search", arXiv:1808.01590 (2018) (`spglib arXiv link`_). + + +============== +How to install +============== +To install, use ``pip install seekpath``. It works both in python 2.7 and +in python 3.5. + +In some distributions (e.g. OpenSuse Leap 42.2), some additional libraries +might be needed, like `python3-devel` and `openblas-devel`. + +If you want to start everything with Docker, you can use the ``Dockerfile`` provided, +or directly the images on `docker hub`_. + +========== +How to use +========== +The main interface of the code is the :py:func:`~seekpath.getpaths.get_path` python function:: + + seekpath.get_path(structure, with_time_reversal, recipe, threshold, symprec, angle_tolerance) + +You need to pass a crystal structure, a boolean flag (``with_time_reversal``) to say if time-reversal symmetry is present or not, and optionally, a recipe (currently only the string ``hpkot`` is supported) and a numerical threshold. + +The format of the structure is described in the function docstring. In particular, +It should be a tuple in the format:: + + (cell, positions, numbers) + +where (if ``N`` is the number of atoms): + +- ``cell`` is a ``3x3`` list of floats (``cell[0]`` is the first lattice vector, ...); +- ``positions`` is a ``Nx3`` list of floats with the atomic coordinates in scaled coordinates (i.e., w.r.t. the cell vectors); +- ``numbers`` is a length-``N`` list with integers identifying uniquely the atoms in the cell. + +The output of the function is a dictionary containing, among other quantities, the k-vector coefficients, the suggested band path, whether the system has inversion symmetry, the crystallographic primitive lattice, the reciprocal primitive lattice. +A detailed description of all output information and their format can be found in the function docstring. (Note that the ``threshold`` is the one used by seekpath to identify +e.g. the order of axes in an orthorhombic cell; instead ``symprec`` and ``angle_tolerance`` are just passed to spglib). + +--------------------------------------------------------------- +A warning on how to use (and crystal structure standardization) +--------------------------------------------------------------- +SeeK-path standardizes the crystal structure +(e.g., rotates the tetragonal system so that the *c* axis is along *z*, +etc.) and can compute the suggested band paths only of standardized +(crystallographic) primitive cells. Therefore, the +**correct approach to use this tool is the following**: + +1. You first find the standardized primitive cell with SeeK-path (returned in + output) and store it somewhere, together with the k-point coordinates + and suggested band path + +2. You then run all your calculations using the standardized primitive cell + +If you already have done calculations with a non-standardized cell, you will +then need to figure out how to remap the labeled k-points in the choice of +cell you did. + +--------------- +Explicit k path +--------------- + +You might also be interested in the :py:func:`~seekpath.getpaths.get_explicit_k_path` function:: + + seekpath.get_explicit_k_path + +that has a very similar interface, that produces an explicit list of k-points along +the suggested band path. The function has the same interface as :py:func:`~seekpath.getpaths.get_path`, but +has also an additional optional parameter ``reference_distance``, that is used as a reference target distance between neighboring k-points along the path. More detailed information can be found in the docstrings of :py:func:`~seekpath.getpaths.get_explicit_k_path`. + +================= +AiiDA integration +================= +If you use AiiDA, you might be interested to use the wrappers that are provided in AiiDA. + +The documentation of the methods can be found at +http://aiida-core.readthedocs.io/en/latest/datatypes/kpoints.html + +--------------- +Legacy wrappers +--------------- + +.. deprecated:: 1.8 + This section describes deprecated methods for back-compatibility reasons. + Until seekpath version 1.7, AiiDA wrappers were included into + seekpath itself. They have now been included in AiiDA. + + These methods will be removed in future versions of seekpath. + +If you use `AiiDA`_, you might be interested in replacing the above +functions with the following wrappers, instead: :py:func:`~seekpath.aiidawrappers.get_path`, +:py:func:`~seekpath.aiidawrappers.get_explicit_k_path`. + +The function interfaces are very similar, but the advantage is that these functions expect an AiiDA structure as +input (instead of a tuple) and return AiiDA structures and KpointsData classes instead of lists and tuples, +where appropriate. Also in this case, additional information is found in the docstrings. + + + +.. _HPKOT paper: http://dx.doi.org/10.1016/j.commatsci.2016.10.015 +.. _JOURNAL LINK: http://dx.doi.org/10.1016/j.commatsci.2016.10.015 +.. _arXiv link: https://arxiv.org/abs/1602.06402 +.. _spglib: http://atztogo.github.io/spglib/ +.. _Materials Cloud: http://www.materialscloud.org/tools/seekpath/ +.. _docker hub: https://hub.docker.com/r/giovannipizzi/seekpath/ +.. _AiiDA: http://www.aiida.net +.. _spglib arXiv link: https://arxiv.org/abs/1808.01590 diff --git a/docs/source/module_guide/index.rst b/docs/source/module_guide/index.rst new file mode 100644 index 0000000..94e9d23 --- /dev/null +++ b/docs/source/module_guide/index.rst @@ -0,0 +1,30 @@ +Python modules documentation +++++++++++++++++++++++++++++ + +SeeK-path +--------- + +.. automodule:: seekpath.getpaths + :members: + + + +The HPKOT module +---------------- + +.. automodule:: seekpath.hpkot + :members: + +.. automodule:: seekpath.hpkot.spg_mapping + :members: + +.. automodule:: seekpath.hpkot.tools + :members: + + +Legacy AiiDA wrappers +--------------------- + +.. automodule:: seekpath.aiidawrappers + :members: +