diff --git a/.github/workflows/slack_notification.yaml b/.github/workflows/slack_notification.yaml deleted file mode 100644 index f34b5de64..000000000 --- a/.github/workflows/slack_notification.yaml +++ /dev/null @@ -1,21 +0,0 @@ -name: Slack-notification - -on: - pull_request: - types: [assigned, review_requested] - -jobs: - SlackNotification: - runs-on: ubuntu-latest - steps: - - name: Slack Notification - run: > - curl -X POST -H 'Content-type: application/json' - --data '{"attachments": [{ - "title": "Pull request: ${{ github.event.pull_request.title }}", - "text": "${{ github.event.pull_request.html_url }}\nReview requested: ${{ github.event.pull_request.requested_reviewers }}", - "author_name": "${{ github.actor }}", - "author_icon": "${{ github.event.sender.avatar_url }}" - }]}' - "${{ secrets.SLACK_WEBHOOK_URL }}" - diff --git a/README.md b/README.md index 72266f3fa..3d51e1c17 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,11 @@ Pip install the following packages, which are also listed in `requirements.txt`: - pyscf - sphinx -- sphinx-material - sphinxcontrib-bibtex - nbsphinx +- pydata-sphinx-theme +- myst-parser +- sphinx_design If you have multiple versions of PySCF on your machine and you would like so use a specific version, set `PYTHONPATH` to include the specific PySCF source @@ -59,45 +61,18 @@ Finally to serve the website, you can run: python -m http.server --directory build/html ``` +### Viewing a forked repo GitHub Pages -### Adding Content to GitHub Pages +The PySCF website is currently built and deployed to GitHub Pages any time a push is made to the master branch of the repository. +The website is served out of the `docs/` directory of the `gh-pages` branch. +This is all controlled by a GitHub Action in `.github/workflows/docs_deploy.yaml`. +If you forked this repository and you want to view the website on your own GitHub Pages, make sure to enable Actions on your repository, +because they are disabled in forks by default. -If you want to show the latest version of the docs on GitHub pages, build using then instructions above. Then from `pyscf-doc/source` run the following: +## How to contribute -```bash -make gh_pages_setup -``` - -## How to Contribute - -1. Add a rst file \"your\_method.rst\" in the [source/user](source/user/) directory in which one describes the basic theory and usage of the method. Reference \"user/your\_method.rst\" in the \"toctree\" section in [source/user.rst](source/user.rst). -2. Add a rst file \"your\_module.rst\" in the [source/modules](source/modules/) directory in which one lists the examples and the member classes and functions of the module (the API doc is then generated by autodoc). (In the \"\_\_init\_\_.py\" file of each module, one should include a simple usage section. See [pyscf.dft.\_\_init\_\_.py](https://github.com/pyscf/pyscf/blob/master/pyscf/dft/__init__.py) as an example.) Reference \"your\_module.rst\" in the \"toctree\" section in [source/modules.rst](source/modules.rst). -3. Optionally, one could also add a rst file \"your\_method\_develop.rst\" in the [source/develop](source/develop/) directory where one provides more detailed descriptions of the implementation and advanced guidelines for using and further development of the module. Reference \"your\_method\_develop.rst\" in [source/develop.rst](source/develop.rst). - - - +1. Add a rst (or md) file \"your\_method.rst\" in the [source/user](source/user/) directory in which one describes the basic theory and usage of the method. Reference \"user/your\_method.rst\" in the \"toctree\" section in [source/user.rst](source/user.rst). +2. Add a rst (or md) file \"your\_module.rst\" in the [source/modules](source/modules/) directory in which one lists the examples and the member classes and functions of the module (the API doc is then generated by autodoc). (In the \"\_\_init\_\_.py\" file of each module, one should include a simple usage section. See [pyscf.dft.\_\_init\_\_.py](https://github.com/pyscf/pyscf/blob/master/pyscf/dft/__init__.py) as an example.) Reference \"your\_module.rst\" in the \"toctree\" section in [source/modules.rst](source/modules.rst). +3. Optionally, one could also add a rst file \"your\_method\_develop.rst\" in the [source/contributor](source/contributor/) directory where one provides more detailed descriptions of the implementation and advanced guidelines for using and further development of the module. diff --git a/requirements.txt b/requirements.txt index b997ce7e8..69d0f0d2d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,9 +1,11 @@ pyscf sphinx -ablog -sphinx-material sphinxcontrib-bibtex nbsphinx Pygments==2.15.0 # MarkupSafe 2.1.1 breaks Jinja2 2.10.1 MarkupSafe==2.0.1 +pydata-sphinx-theme +myst-parser +sphinx_design + diff --git a/source/_static/css/pyscf.css b/source/_static/css/pyscf-material.css similarity index 100% rename from source/_static/css/pyscf.css rename to source/_static/css/pyscf-material.css diff --git a/source/_static/css/pyscf-pst.css b/source/_static/css/pyscf-pst.css new file mode 100644 index 000000000..e8ca548cb --- /dev/null +++ b/source/_static/css/pyscf-pst.css @@ -0,0 +1,14 @@ +:root { + --pyscf-primary: #3677e0; + --pyscf-accent: #3677e0; +} + +html[data-theme="light"] { + --pst-color-primary: var(--pyscf-primary); + --pst-color-secondary: var(--pyscf-accent); +} + +html[data-theme="dark"] { + --pst-color-primary: var(--pyscf-primary); + --pst-color-secondary: var(--pyscf-accent); +} diff --git a/source/about.md b/source/about.md new file mode 100644 index 000000000..51078c88f --- /dev/null +++ b/source/about.md @@ -0,0 +1,47 @@ +# About PySCF + +PySCF is a free and open-source quantum chemistry code distributed on +[GitHub](https://github.com/pyscf/pyscf) and released under the Apache-2.0 +license. The development of PySCF began in 2014. Since then, it has grown +from being a single-group code to one relied on daily by over 100 research +teams in academia and industry across the world. For more details, see its +extensive list of [features](features.rst), [version history](version), and +example [benchmark data](benchmark). + +## People + +### Board of directors + +- [Timothy Berkelbach](https://berkelbach.chem.columbia.edu/), Columbia and Flatiron Institute +- [Garnet Chan](https://www.chan-lab.caltech.edu/), Caltech +- [Sandeep Sharma](https://www.colorado.edu/lab/sharmagroup/), CU Boulder +- [Alexander Sokolov](https://research.cbc.osu.edu/sokolov.8/), Ohio State +- Qiming Sun + +### Maintainers + +- [Xing Zhang](https://www.chan-lab.caltech.edu/people), Caltech + +## How to cite + +- [Recent developments in the PySCF program package](https://doi.org/10.1063/5.0006074), Q. Sun, X. Zhang, S. Banerjee, P. Bao, M. Barbry, N. S. Blunt, N. A. Bogdanov, G. H. Booth, J. Chen, Z.-H. Cui, J. J. Eriksen, Y. Gao, S. Guo, J. Hermann, M. R. Hermes, K. Koh, P. Koval, S. Lehtola, Z. Li, J. Liu, N. Mardirossian, J. D. McClain, M. Motta, B. Mussard, H. Q. Pham, A. Pulkin, W. Purwanto, P. J. Robinson, E. Ronca, E. R. Sayfutyarova, M. Scheurer, H. F. Schurkus, J. E. T. Smith, C. Sun, S.-N. Sun, S. Upadhyay, L. K. Wagner, X. Wang, A. White, J. Daniel Whitfield, M. J. Williamson, S. Wouters, J. Yang, J. M. Yu, T. Zhu, T. C. Berkelbach, S. Sharma, A. Yu. Sokolov, and G. K.-L. Chan, J. Chem. Phys. **153**, 024109 (2020) + +- [PySCF: the Python-based simulations of chemistry framework](https://doi.org/10.1002/wcms.1340), Q. Sun, T. C. Berkelbach, N. S. Blunt, G. H. Booth, S. Guo, Z. Li, J. Liu, J. McClain, S. Sharma, S. Wouters, and G. K.-L. Chan, WIREs Comput. Mol. Sci. **8**, e1340 (2018) + +- [Libcint: An efficient general integral library for Gaussian basis functions](https://doi.org/10.1002/jcc.23981), Q. Sun, J. Comp. Chem. 36, 1664 (2015) + +## Funding + +The development of PySCF has been and continues to be generously supported by a +number of funding agencies. Most of the molecular quantum chemistry software +infrastructure was developed with support from the US National Science +Foundation, through grants CHE-1650436 and ACI-1657286. The periodic mean-field +infrastructure was developed with support from ACI-1657286. The excited-state +periodic coupled cluster methods were developed with support from the US +Department of Energy, Office of Science, through the grants DE-SC0010530 and +DE-SC0008624. Additional support for the extended-system methods has been +provided by the Simons Foundation through the Flatiron Institute, the Simons +Collaboration on the Many Electron Problem, a Simons Investigatorship in +Theoretical Physics, the Princeton Center for Theoretical Science, and startup +funds from Princeton University and the California Institute of Technology. + diff --git a/source/about.rst b/source/about.rst deleted file mode 100644 index 6e482d39e..000000000 --- a/source/about.rst +++ /dev/null @@ -1,38 +0,0 @@ -About -===== - -The development of PySCF began in 2014. Since then, it has changed from being a single-group code to one relied on daily by over 100 research teams in academia and industry across the world. -For more details, see its extensive `list of features `_, `version history `_, and example `benchmark data `_. - -People --------- - -Board of directors -"""""""""""""""""" -- `Timothy Berkelbach `_, Columbia and Flatiron Institute -- `Garnet Chan `_, Caltech -- `Sandeep Sharma `_, UC Boulder -- `Alexander Sokolov `_, Ohio State -- `Qiming Sun `_, Axiomquant LLC - -Maintainers -""""""""""" -- Zhihao Cui, Caltech -- Yang Gao, Caltech -- Iliya Sabzevari, UC Boulder -- James Smith, Flatiron Institute -- Xiao Wang, Flatiron Institute - -How to cite ------------ - -- `Recent developments in the PySCF program package `_, Q. Sun, X. Zhang, S. Banerjee, P. Bao, M. Barbry, N. S. Blunt, N. A. Bogdanov, G. H. Booth, J. Chen, Z.-H. Cui, J. J. Eriksen, Y. Gao, S. Guo, J. Hermann, M. R. Hermes, K. Koh, P. Koval, S. Lehtola, Z. Li, J. Liu, N. Mardirossian, J. D. McClain, M. Motta, B. Mussard, H. Q. Pham, A. Pulkin, W. Purwanto, P. J. Robinson, E. Ronca, E. R. Sayfutyarova, M. Scheurer, H. F. Schurkus, J. E. T. Smith, C. Sun, S.-N. Sun, S. Upadhyay, L. K. Wagner, X. Wang, A. White, J. Daniel Whitfield, M. J. Williamson, S. Wouters, J. Yang, J. M. Yu, T. Zhu, T. C. Berkelbach, S. Sharma, A. Yu. Sokolov, and G. K.-L. Chan, J. Chem. Phys. **153**, 024109 (2020) - -- `PySCF: the Python-based simulations of chemistry framework `_, Q. Sun, T. C. Berkelbach, N. S. Blunt, G. H. Booth, S. Guo, Z. Li, J. Liu, J. McClain, S. Sharma, S. Wouters, and G. K.-L. Chan, WIREs Comput. Mol. Sci. **8**, e1340 (2018) - -- `Libcint: An efficient general integral library for Gaussian basis functions `_, Q. Sun, J. Comp. Chem. 36, 1664 (2015) - -Funding -------- - -The development of PySCF has been and continues to be generously supported by a number of funding agencies. Most of the molecular quantum chemistry software infrastructure was developed with support from the US National Science Foundation, through grants CHE-1650436 and ACI-1657286. The periodic mean-field infrastructure was developed with support from ACI-1657286. The excited-state periodic coupled cluster methods were developed with support from the US Department of Energy, Office of Science, through the grants DE-SC0010530 and DE-SC0008624. Additional support for the extended-system methods has been provided by the Simons Foundation through the Flatiron Institute, the Simons Collaboration on the Many Electron Problem, a Simons Investigatorship in Theoretical Physics, the Princeton Center for Theoretical Science, and startup funds from Princeton University and the California Institute of Technology. diff --git a/source/conf.py b/source/conf.py index 5789ab628..96d4414cb 100644 --- a/source/conf.py +++ b/source/conf.py @@ -2,166 +2,12 @@ # import os import sys - -# import ablog +from datetime import datetime from pyscf import __version__ sys.path.append("./source/tools/extensions") - -# -- General ABlog Options ---------------------------------------------------- - -# A path relative to the configuration directory for blog archive pages. -# blog_path = 'blog' - -# The "title" for the blog, used in active pages. Default is ``'Blog'``. -blog_title = u"PySCF Docs" - -# Base URL for the website, required for generating feeds. -# e.g. blog_baseurl = "http://example.com/" -blog_baseurl = u"" - -# Choose to archive only post titles. Archiving only titles can speed -# up project building. -# blog_archive_titles = False - -# -- Blog Authors, Languages, and Locations ----------------------------------- - -# A dictionary of author names mapping to author full display names and -# links. Dictionary keys are what should be used in ``post`` directive -# to refer to the author. Default is ``{}``. -blog_authors = {"James E. T. Smith": ("James E. T. Smith", None)} - - -# A dictionary of language code names mapping to full display names and -# links of these languages. Similar to :confval:`blog_authors`, dictionary -# keys should be used in ``post`` directive to refer to the locations. -# Default is ``{}``. -# blog_languages = { -# 'en': ('English', None), -# } - - -# A dictionary of location names mapping to full display names and -# links of these locations. Similar to :confval:`blog_authors`, dictionary -# keys should be used in ``post`` directive to refer to the locations. -# Default is ``{}``. -# blog_locations = { -# 'Earth': ('The Blue Planet', 'https://en.wikipedia.org/wiki/Earth), -# } - -# -- Blog Post Related -------------------------------------------------------- - -# Format date for a post. -# post_date_format = '%b %d, %Y' - -# Number of paragraphs (default is ``1``) that will be displayed as an excerpt -# from the post. Setting this ``0`` will result in displaying no post excerpt -# in archive pages. This option can be set on a per post basis using -# post_auto_excerpt = 1 - -# Index of the image that will be displayed in the excerpt of the post. -# Default is ``0``, meaning no image. Setting this to ``1`` will include -# the first image, when available, to the excerpt. This option can be set -# on a per post basis using :rst:dir:`post` directive option ``image``. -# post_auto_image = 0 - -# Number of seconds (default is ``5``) that a redirect page waits before -# refreshing the page to redirect to the post. -# post_redirect_refresh = 5 - -# When ``True``, post title and excerpt is always taken from the section that -# contains the :rst:dir:`post` directive, instead of the document. This is the -# behavior when :rst:dir:`post` is used multiple times in a document. Default -# is ``False``. -# post_always_section = False - -# When ``False``, the :rst:dir:`orphan` directive is not automatically set -# for each post. Without this directive, Sphinx will warn about posts that -# are not explicitly referenced via another document. :rst:dir:`orphan` can -# be set on a per-post basis as well if this is false. Default is ``True``. -# post_auto_orphan = True - -# -- ABlog Sidebars ------------------------------------------------------- - -# There are seven sidebars you can include in your HTML output. -# postcard.html provides information regarding the current post. -# recentposts.html lists most recent five posts. Others provide -# a link to a archive pages generated for each tag, category, and year. -# In addition, there are authors.html, languages.html, and locations.html -# sidebars that link to author and location archive pages. -html_sidebars = { - "**": [ - # "about.html", - # "postcard.html", - # "navigation.html", - # "recentposts.html", - # "tagcloud.html", - # "categories.html", - # "archives.html", - "searchbox.html", - "logo-text.html", - "globaltoc.html", - "localtoc.html", - ], - #"index": [ - # "searchbox.html", - # #"logo-text.html", - #] -} - -# -- Blog Feed Options -------------------------------------------------------- - -# Turn feeds by setting :confval:`blog_baseurl` configuration variable. -# Choose to create feeds per author, location, tag, category, and year, -# default is ``False``. -# blog_feed_archives = False - -# Choose to display full text in blog feeds, default is ``False``. -# blog_feed_fulltext = False - -# Blog feed subtitle, default is ``None``. -# blog_feed_subtitle = None - -# Choose to feed only post titles, default is ``False``. -# blog_feed_titles = False - -# Specify number of recent posts to include in feeds, default is ``None`` -# for all posts. -# blog_feed_length = None - -# -- Font-Awesome Options ----------------------------------------------------- - -# ABlog templates will use of Font Awesome icons if one of the following -# is ``True`` - -# Link to `Font Awesome`_ at `Bootstrap CDN`_ and use icons in sidebars -# and post footers. Default: ``None`` -# fontawesome_link_cdn = None - -# Sphinx_ theme already links to `Font Awesome`_. Default: ``False`` -# fontawesome_included = False - -# Alternatively, you can provide the path to `Font Awesome`_ :file:`.css` -# with the configuration option: fontawesome_css_file -# Path to `Font Awesome`_ :file:`.css` (default is ``None``) that will -# be linked to in HTML output by ABlog. -# fontawesome_css_file = None - -# -- Disqus Integration ------------------------------------------------------- - -# You can enable Disqus_ by setting ``disqus_shortname`` variable. -# Disqus_ short name for the blog. -# disqus_shortname = None - -# Choose to disqus pages that are not posts, default is ``False``. -# disqus_pages = False - -# Choose to disqus posts that are drafts (without a published date), -# default is ``False``. -# disqus_drafts = False - # -- Sphinx Options ----------------------------------------------------------- # If your project needs a minimal Sphinx version, state it here. @@ -181,22 +27,20 @@ "sphinxcontrib.bibtex", "nbsphinx", "pyscfdocext", - # "ablog", + "myst_parser", + "sphinx_design", + "gallery_directive", ] bibtex_bibfiles = ['user/ref.bib'] myst_update_mathjax = False +myst_enable_extensions = [ + "colon_fence", + "dollarmath", +] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] -# templates_path = ["_templates", ablog.get_html_templates_path()] - -# The suffix(es) of source filenames. -source_suffix = { - ".rst": "restructuredtext", - # ".txt": "markdown", - # ".md": "markdown", -} # The encoding of source files. # source_encoding = 'utf-8-sig' @@ -206,7 +50,8 @@ # General information about the project. project = u"PySCF" -copyright = u"2015-2021, The PySCF Developers" +year = datetime.now().year +copyright = f"{year}, The PySCF Developers" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -267,40 +112,92 @@ # -- Options for HTML output ---------------------------------------------- +# 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 theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "sphinx_material" +#html_theme = "sphinx_material" +html_theme = "pydata_sphinx_theme" # 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 = { - # "github_button": False, - "repo_name": "PySCF", - "repo_url": "https://github.com/pyscf/pyscf/", - "nav_title": "PySCF {0}".format(version), - #"color_primary": "blue", - #"color_accent": "amber", - "color_primary": "pyscf", - "color_accent": "pyscf", - "globaltoc_depth": 2, - "globaltoc_collapse": True, - "master_doc": False, - "heroes": {"index": "The Python-based Simulations of Chemistry Framework"}, - "nav_links": [ - {"href": "index", "title": "Home", "internal": True}, - #{"href": "overview", "title": "Overview", "internal": True}, - {"href": "install", "title": "Install", "internal": True}, - {"href": "quickstart", "title": "Quickstart", "internal": True}, - {"href": "user", "title": "User Guide", "internal": True}, - {"href": "develop", "title": "Developer Guide", "internal": True}, - {"href": "pyscf_api_docs/modules", "title": "API", "internal": True}, - # {"href": "blog_wrapper", "title": "Blog", "internal": True}, - {"href": "about", "title": "About", "internal": True}, - ], - "table_classes": ["simple"], + +if html_theme == 'sphinx_material': + html_css_files = ["css/pyscf-material.css"] + html_theme_options = { + # "github_button": False, + "repo_name": "PySCF", + "repo_url": "https://github.com/pyscf/pyscf/", + "nav_title": "PySCF {0}".format(version), + #"color_primary": "blue", + #"color_accent": "amber", + "color_primary": "pyscf", + "color_accent": "pyscf", + "globaltoc_depth": 2, + "globaltoc_collapse": True, + "master_doc": False, + "heroes": {"index": "The Python-based Simulations of Chemistry Framework"}, + "nav_links": [ + {"href": "index", "title": "Home", "internal": True}, + #{"href": "overview", "title": "Overview", "internal": True}, + {"href": "install", "title": "Install", "internal": True}, + {"href": "quickstart", "title": "Quickstart", "internal": True}, + {"href": "user", "title": "User Guide", "internal": True}, + {"href": "develop", "title": "Developer Guide", "internal": True}, + {"href": "pyscf_api_docs/modules", "title": "API", "internal": True}, + {"href": "about", "title": "About", "internal": True}, + ], + "table_classes": ["simple"], + } + + # The name of an image file (relative to this directory) to place at the top + # of the sidebar. + html_logo = "../logo/pyscf-logo-white.svg" + + +if html_theme == 'pydata_sphinx_theme': + html_css_files = ["css/pyscf-pst.css"] + html_context = { + "github_user": "pyscf", + "github_repo": "pyscf.github.io", + "github_version": "master", + "doc_path": "source", + } + + html_theme_options = { + "logo": { + "text": "PySCF", + "image_light": "../logo/logo-64x64.png", + "image_dark": "../logo/logo-64x64.png", + }, + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/pyscf/pyscf", + "icon": "fa-brands fa-github", + "type": "fontawesome", + }, + ], + "use_edit_page_button": True, + "show_toc_level": 1, + "secondary_sidebar_items": { + "**": ["page-toc", "edit-this-page"], + }, + # "navbar_align": "left", + } + +html_sidebars = { + "install": [], + "quickstart": [], + "about": [], } + # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [alabaster.get_path()] @@ -311,21 +208,11 @@ # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = "PySCF" -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -html_logo = "../logo/pyscf-logo-white.svg" - # 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 = "../logo/favicon-32x32.png" -# 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"] -html_css_files = ["css/pyscf.css"] - # 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. diff --git a/source/develop/agf2_developer.rst b/source/contributor/agf2_developer.rst similarity index 100% rename from source/develop/agf2_developer.rst rename to source/contributor/agf2_developer.rst diff --git a/source/develop/ao2mo_developer.rst b/source/contributor/ao2mo_developer.rst similarity index 100% rename from source/develop/ao2mo_developer.rst rename to source/contributor/ao2mo_developer.rst diff --git a/source/develop/cc_developer.rst b/source/contributor/cc_developer.rst similarity index 100% rename from source/develop/cc_developer.rst rename to source/contributor/cc_developer.rst diff --git a/source/develop/ci_developer.rst b/source/contributor/ci_developer.rst similarity index 100% rename from source/develop/ci_developer.rst rename to source/contributor/ci_developer.rst diff --git a/source/develop/cisd.rst b/source/contributor/cisd.rst similarity index 100% rename from source/develop/cisd.rst rename to source/contributor/cisd.rst diff --git a/source/code-rule.rst b/source/contributor/code-standard.rst similarity index 100% rename from source/code-rule.rst rename to source/contributor/code-standard.rst diff --git a/source/develop/df_developer.rst b/source/contributor/df_developer.rst similarity index 100% rename from source/develop/df_developer.rst rename to source/contributor/df_developer.rst diff --git a/source/develop/dft_developer.rst b/source/contributor/dft_developer.rst similarity index 100% rename from source/develop/dft_developer.rst rename to source/contributor/dft_developer.rst diff --git a/source/develop/eph_developer.rst b/source/contributor/eph_developer.rst similarity index 100% rename from source/develop/eph_developer.rst rename to source/contributor/eph_developer.rst diff --git a/source/develop/fci_developer.rst b/source/contributor/fci_developer.rst similarity index 100% rename from source/develop/fci_developer.rst rename to source/contributor/fci_developer.rst diff --git a/source/develop/gto_developer.rst b/source/contributor/gto_developer.rst similarity index 100% rename from source/develop/gto_developer.rst rename to source/contributor/gto_developer.rst diff --git a/source/contributor/index.md b/source/contributor/index.md new file mode 100644 index 000000000..531375beb --- /dev/null +++ b/source/contributor/index.md @@ -0,0 +1,11 @@ +# Contributor Guide + +A more complete Contributor Guide for PySCF is planned for the future. + +```{toctree} +:caption: Style guide +:maxdepth: 1 + +code-standard +``` + diff --git a/source/develop/mcscf_developer.rst b/source/contributor/mcscf_developer.rst similarity index 100% rename from source/develop/mcscf_developer.rst rename to source/contributor/mcscf_developer.rst diff --git a/source/develop/pbc_developer.rst b/source/contributor/pbc_developer.rst similarity index 100% rename from source/develop/pbc_developer.rst rename to source/contributor/pbc_developer.rst diff --git a/source/develop/scf_developer.rst b/source/contributor/scf_developer.rst similarity index 100% rename from source/develop/scf_developer.rst rename to source/contributor/scf_developer.rst diff --git a/source/develop/soscf_developer.rst b/source/contributor/soscf_developer.rst similarity index 100% rename from source/develop/soscf_developer.rst rename to source/contributor/soscf_developer.rst diff --git a/source/develop/table.png b/source/contributor/table.png similarity index 100% rename from source/develop/table.png rename to source/contributor/table.png diff --git a/source/develop/tdscf_developer.rst b/source/contributor/tdscf_developer.rst similarity index 100% rename from source/develop/tdscf_developer.rst rename to source/contributor/tdscf_developer.rst diff --git a/source/index.md b/source/index.md new file mode 100644 index 000000000..211bf83c8 --- /dev/null +++ b/source/index.md @@ -0,0 +1,49 @@ +--- +html_theme.sidebar_secondary.remove: true +--- + +# Quantum chemistry with Python + + +```{gallery-grid} +:grid-columns: 1 2 2 3 + +- header: "{fab}`python;pst-color-primary` Primarily Python" + content: "Easy to read and write, for quick development with fewer mistakes." +- header: "{fas}`bolt;pst-color-primary` Fast" + content: "Uses NumPy, SciPy, and custom C/C++ code." +- header: "{fa}`code-branch;pst-color-primary` Free and open-source" + content: "Accessible and community-driven. Distributed on [GitHub](https://github.com/pyscf/pyscf) under the [Apache-2.0](https://github.com/pyscf/pyscf/tree/master?tab=Apache-2.0-1-ov-file#readme) license." +- header: "{fas}`gears;pst-color-primary` Modular" + content: "Easily integrated into complex workflows or other software packages." +- header: "{fa}`list-ul;pst-color-primary` Comprehensive" + content: "Extensive collection of electronic structure methods, for molecules and periodic solids." +- header: "{fas}`lightbulb;pst-color-primary` Extensible" + content: "See the list of [Extensions](user/extensions) to PySCF." +``` + + + + +```{toctree} +:hidden: + +quickstart +user/index +contributor/index +About +``` diff --git a/source/index.rst b/source/index.rst deleted file mode 100644 index 9b73c36ae..000000000 --- a/source/index.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. PySCF - -Home -**** - -.. image:: ../logo/pyscf-logo.png - :width: 400 - -The Python-based Simulations of Chemistry Framework (PySCF) is an open-source -collection of electronic structure modules powered by Python. The package -provides a simple, lightweight, and efficient platform for quantum chemistry -calculations and methodology development. -PySCF can be used to simulate the properties of molecules, crystals, and -custom Hamiltonians using mean-field and post-mean-field methods. -To ensure ease of extensibility, almost all of the features in PySCF are -implemented in Python, while computationally critical parts are -implemented and optimized in C. Using this combined Python/C -implementation, the package is as efficient as the best existing C or Fortran -based quantum chemistry programs. -In addition to its core libraries, PySCF supports a rich -ecosystem of :ref:`installing_extproj`. - -.. MPI versions of some routines, additional quantum chemistry methods and analysis, interface with quantum computing toolkits *etc*. See :ref:`installing_extproj`. - -.. For installation instructions, see the :ref:`install` page. - -.. For a guide to performing a variety of calculations with PySCF, see the :ref:`quickstart` guide. - - -.. COMMENTED OUT FOR NOW -.. Install -.. User Guide -.. Developer Guide -.. API Docs -.. Blog -.. Modules -.. about.md - -.. toctree:: - :hidden: - :maxdepth: 1 - - Install - Quickstart - User Guide - Developer Guide - API - About - -.. You can also download the `PDF version `_ of this manual. - - -.. Indices and tables -.. ================== -.. -.. * :ref:`genindex` -.. * :ref:`modindex` -.. * :ref:`search` diff --git a/source/tools/extensions/gallery_directive.py b/source/tools/extensions/gallery_directive.py new file mode 100644 index 000000000..ab275335c --- /dev/null +++ b/source/tools/extensions/gallery_directive.py @@ -0,0 +1,145 @@ +"""A directive to generate a gallery of images from structured data. + +Generating a gallery of images that are all the same size is a common +pattern in documentation, and this can be cumbersome if the gallery is +generated programmatically. This directive wraps this particular use-case +in a helper-directive to generate it with a single YAML configuration file. + +It currently exists for maintainers of the pydata-sphinx-theme, +but might be abstracted into a standalone package if it proves useful. +""" + +from pathlib import Path +from typing import Any, ClassVar, Dict, List + +from docutils import nodes +from docutils.parsers.rst import directives +from sphinx.application import Sphinx +from sphinx.util import logging +from sphinx.util.docutils import SphinxDirective +from yaml import safe_load + +logger = logging.getLogger(__name__) + + +TEMPLATE_GRID = """ +`````{{grid}} {columns} +{options} + +{content} + +````` +""" + +GRID_CARD = """ +````{{grid-item-card}} {title} +{options} + +{content} +```` +""" + + +class GalleryGridDirective(SphinxDirective): + """A directive to show a gallery of images and links in a Bootstrap grid. + + The grid can be generated from a YAML file that contains a list of items, or + from the content of the directive (also formatted in YAML). Use the parameter + "class-card" to add an additional CSS class to all cards. When specifying the grid + items, you can use all parameters from "grid-item-card" directive to customize + individual cards + ["image", "header", "content", "title"]. + + Danger: + This directive can only be used in the context of a Myst documentation page as + the templates use Markdown flavored formatting. + """ + + name = "gallery-grid" + has_content = True + required_arguments = 0 + optional_arguments = 1 + final_argument_whitespace = True + option_spec: ClassVar[dict[str, Any]] = { + # A class to be added to the resulting container + "grid-columns": directives.unchanged, + "class-container": directives.unchanged, + "class-card": directives.unchanged, + } + + def run(self) -> List[nodes.Node]: + """Create the gallery grid.""" + if self.arguments: + # If an argument is given, assume it's a path to a YAML file + # Parse it and load it into the directive content + path_data_rel = Path(self.arguments[0]) + path_doc, _ = self.get_source_info() + path_doc = Path(path_doc).parent + path_data = (path_doc / path_data_rel).resolve() + if not path_data.exists(): + logger.info(f"Could not find grid data at {path_data}.") + nodes.text("No grid data found at {path_data}.") + return + yaml_string = path_data.read_text() + else: + yaml_string = "\n".join(self.content) + + # Use all the element with an img-bottom key as sites to show + # and generate a card item for each of them + grid_items = [] + for item in safe_load(yaml_string): + # remove parameters that are not needed for the card options + title = item.pop("title", "") + + # build the content of the card using some extra parameters + header = f"{item.pop('header')} \n^^^ \n" if "header" in item else "" + image = f"![image]({item.pop('image')}) \n" if "image" in item else "" + content = f"{item.pop('content')} \n" if "content" in item else "" + + # optional parameter that influence all cards + if "class-card" in self.options: + item["class-card"] = self.options["class-card"] + + loc_options_str = "\n".join(f":{k}: {v}" for k, v in item.items()) + " \n" + + card = GRID_CARD.format( + options=loc_options_str, content=header + image + content, title=title + ) + grid_items.append(card) + + # Parse the template with Sphinx Design to create an output container + # Prep the options for the template grid + class_ = "gallery-directive" + f' {self.options.get("class-container", "")}' + options = {"gutter": 2, "class-container": class_} + options_str = "\n".join(f":{k}: {v}" for k, v in options.items()) + + # Create the directive string for the grid + grid_directive = TEMPLATE_GRID.format( + columns=self.options.get("grid-columns", "1 2 3 4"), + options=options_str, + content="\n".join(grid_items), + ) + + # Parse content as a directive so Sphinx Design processes it + container = nodes.container() + self.state.nested_parse([grid_directive], 0, container) + + # Sphinx Design outputs a container too, so just use that + return [container.children[0]] + + +def setup(app: Sphinx) -> Dict[str, Any]: + """Add custom configuration to sphinx app. + + Args: + app: the Sphinx application + + Returns: + the 2 parallel parameters set to ``True``. + """ + app.add_directive("gallery-grid", GalleryGridDirective) + + return { + "parallel_read_safe": True, + "parallel_write_safe": True, + } + diff --git a/source/user.rst b/source/user.rst deleted file mode 100644 index eabb61f0a..000000000 --- a/source/user.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _theory: - -User Guide -********** - -A variety of electronic structure methods are implemented in the PySCF package. -Many of them can also be used for solid-state calculations with periodic boundary conditions. -This User Guide introduces the basic theories of these methods and demonstrates their main -functionalities. - - -.. toctree:: - :maxdepth: 1 - - user/gto.rst - user/scf.rst - user/dft.rst - user/mp.rst - user/gw.rst - user/ci.rst - user/cc.rst - user/adc.rst - user/agf2.rst - user/mcscf.rst - user/mrpt.rst - user/tddft.rst - user/solvent.rst - user/qmmm.rst - user/md.rst - user/df.rst - user/pbc.rst - user/eph.rst - user/lo.rst - user/sgx.rst - user/geomopt.rst - user/gpu.rst - user/reference.rst - diff --git a/source/user/extensions.md b/source/user/extensions.md new file mode 100644 index 000000000..bd8baa32e --- /dev/null +++ b/source/user/extensions.md @@ -0,0 +1,106 @@ +# Extensions + +Due to its flexibility and modular nature, many extensions have been developed +based on PySCF. As a courtesy, repositories for some of these extensions are +hosted by the [PySCF organization's GitHub](https://github.com/pyscf). However, +the PySCF organization provides no support for these extensions, nor a +guarantee of future compatibility. Questions should be addressed to the authors +of the extension, and issues can be raised on the GitHub repository of the +extension. + +Once an extension module has been correctly installed (see [How to install +extensions](#how-to-install-extensions)), you can use it as a regular submodule +of PySCF, e.g., +```python +import pyscf +from pyscf.semiempirical import MINDO3 +mol = pyscf.M(atom='N 0 0 0; N 0 0 1') +MINDO3(mol).run() +``` + + A list of PySCF extensions is given below. + +| Project | URL | +| --------------- | ------------------------------------------- | +| cas_ac0 | https://github.com/CQCL/pyscf-ac0 | +| cornell-shci | https://github.com/pyscf/cornell-shci | +| dftd3 | https://github.com/pyscf/dftd3 | +| dmrgscf | https://github.com/pyscf/dmrgscf | +| doci | https://github.com/pyscf/doci | +| fciqmc | https://github.com/pyscf/fciqmc | +| icmpspt | https://github.com/pyscf/icmpspt | +| mbd | https://github.com/pyscf/mbd | +| naive-hci | https://github.com/pyscf/naive-hci | +| nao | https://github.com/pyscf/nao | +| qsdopt | https://github.com/pyscf/qsdopt | +| rt | https://github.com/pyscf/rt | +| semiempirical | https://github.com/pyscf/semiempirical | +| shciscf | https://github.com/pyscf/shciscf | +| zquatev | https://github.com/sunqm/zquatev | +| tblis | https://github.com/pyscf/pyscf-tblis | + +## How to install extensions + +Many extension modules (e.g., the semiempirical module) can be +installed using pip's extra dependency mechanism, +```bash +pip install pyscf[semiempirical] +``` + +Although not recommended, all extension modules can be installed, +```bash +pip install pyscf[all] +``` + +## How to install extensions (advanced) + +Based on the technique of namespace packages specified in [PEP +420](https://www.python.org/dev/peps/pep-0420/>), PySCF has developed a couple +of methods to install the extension modules. + +### Pip command + +For pip version newer than 19.0, projects hosted on GitHub can be installed on +the command line, +```bash +pip install git+https://github.com/pyscf/semiempirical +``` + +A particular release on GitHub can be installed with the release URL you can +look up on GitHub, +```bash +pip install https://github.com/pyscf/semiempirical/archive/v0.1.0.tar.gz +``` + +### Pip command for local paths + +If you wish to load an extension module developed in a local directory, you can +use the local install mode of pip. Use of a Python virtual environment is +recommended to avoid polluting the system default Python runtime environment, +for example, +```bash +python -m venv /home/abc/pyscf-local-env +source /home/abc/pyscf-local-env/bin/activate +git clone https://github.com/pyscf/semiempirical /home/abc/semiempirical +pip install -e /home/abc/semiempirical +``` + +### Environment variable `PYSCF_EXT_PATH` + +You can place the location of each extension module (or a file that contains +these locations) in this environment variable. The PySCF library will parse the +paths defined in this environment variable, and load the relevant submodules. +For example, +```bash +git clone https://github.com/pyscf/semiempirical /home/abc/semiempirical +git clone https://github.com/pyscf/doci /home/abc/doci +git clone https://github.com/pyscf/dftd3 /home/abc/dftd3 +echo /home/abc/doci > /home/abc/.pyscf_ext_modules +echo /home/abc/dftd3 >> /home/abc/.pyscf_ext_modules +export PYSCF_EXT_PATH=/home/abc/semiempirical:/home/abc/.pyscf_ext_modules +``` + +Using this definition of `PYSCF_EXT_PATH`, the three extension +submodules (semiempirical, doci, dftd3) are loaded when PySCF is +imported, and you don't have to use a Python virtual environment. + diff --git a/source/user/index.md b/source/user/index.md new file mode 100644 index 000000000..51401aca0 --- /dev/null +++ b/source/user/index.md @@ -0,0 +1,62 @@ +# User Guide + +A variety of electronic structure methods are implemented in the PySCF package. +Many of them can also be used for solid-state calculations with periodic +boundary conditions. This User Guide introduces the basic theories of these +methods and demonstrates their main functionalities. + +```{toctree} +:caption: Getting started +:maxdepth: 1 + +install +using +``` + +```{toctree} +:caption: Building molecules and crystals +:maxdepth: 1 + +gto +pbcgto +``` + +```{toctree} +:caption: Electronic structure methods +:maxdepth: 1 + +scf +dft.rst +mp.rst +gw.rst +ci.rst +cc.rst +adc.rst +agf2.rst +mcscf.rst +mrpt.rst +tddft.rst +``` + +```{toctree} +:caption: Other functionalities +:maxdepth: 1 + +solvent.rst +qmmm.rst +md.rst +df.rst +pbc.rst +eph.rst +lo.rst +sgx.rst +geomopt.rst +gpu.rst +``` + +```{toctree} +:caption: Extensions +:maxdepth: 1 + +extensions +``` diff --git a/source/user/install.md b/source/user/install.md new file mode 100644 index 000000000..a063bd30f --- /dev/null +++ b/source/user/install.md @@ -0,0 +1,377 @@ +# How to install PySCF + +:::{warning} + +PySCF is not supported natively on Windows. You must use the Windows +Subsystem for Linux. + +::: + +## Install with pip + +This is the recommended way to install PySCF for non-developers, +```bash +pip install --prefer-binary pyscf +``` + +The pip package provides a precompiled PySCF code (python wheel) that +works on almost all Linux systems, most macOS systems, and +the Windows Subsystem for Linux. + +If you already have installed +PySCF via pip, you can upgrade it to the new version, +```bash +pip install --upgrade pyscf +``` + +:::{seealso} +Newly introduced features are available in the +[pyscf-forge](https://github.com/pyscf/pyscf-forge) package, which can be +installed with `pip`, +```bash +pip install pyscf-forge +``` +Some other features are only maintained as [Extensions](user/extensions) to PySCF. +::: + +## Build from source with pip + +If you're interested in a new feature that's not included in the latest release or you simply +want the latest and greatest PySCF, you can build from source using pip, +```bash +pip install git+https://github.com/pyscf/pyscf +``` + +To install the features developed on a particular branch, +```bash +pip install git+https://github.com/pyscf/pyscf@ +``` + +This install method compiles and links C extensions against the +libraries in your system. See [Build from source](#build-from-source) for a full +list of prerequisites. If you would like to tune the CMake compilation +parameters, you can set them with the environment variable `CMAKE_CONFIGURE_ARGS`, +for example, +```bash +export CMAKE_CONFIGURE_ARGS="-DBUILD_MARCH_NATIVE=ON -DBLA_VENDOR=Intel10_64lp_seq" +``` + +See [CMake options](#cmake-options) for more details about CMake configuration. + + +## Build from source + +You can manually install PySCF by building it from source. +Prerequisites for manual installation are +- C compiler +- C++ compiler (optional, but required for XCFun and some extensions) +- CMake >= 3.10 +- Python >= 3.7 +- Numpy >= 1.13 +- Scipy >= 1.3 +- h5py >= 2.7 + +You can download the latest version of PySCF (or the development +branch) from GitHub, +```bash +git clone https://github.com/pyscf/pyscf.git +cd pyscf +``` +Next, you need to build the C extensions in `pyscf/lib` +```bash +cd pyscf/lib +mkdir build +cd build +cmake .. +make +``` +This will automatically download the analytical GTO integral library +[libcint](https://github.com/sunqm/libcint.git) and the DFT exchange +correlation functional libraries [Libxc](https://libxc.gitlab.io/) +and [XCFun](https://github.com/dftlibs/xcfun.git). Finally, to allow Python to +find the `pyscf` package, add the top-level `pyscf` directory (not the +`pyscf/pyscf` subdirectory) to `PYTHONPATH`. For example, if `pyscf` +is installed in ``/opt``, you should update `PYTHONPATH` with something +like, +```bash +export PYTHONPATH=/opt/pyscf:$PYTHONPATH +``` + +To ensure that the installation was successful, you can use python to +try to import and pring the PySCF version, +```bash +python -c "import pyscf; print(pyscf.__version__)" +``` + +See [CMake options](#cmake-options) for details about CMake configuration. + + +## Install with conda + +If you have a [Conda](https://conda.io/docs/) (or +[Anaconda](https://www.continuum.io/downloads) environment, PySCF +package can be installed from the Conda cloud (for Linux and macOS +systems), +```bash +conda install -c pyscf pyscf +``` + + + +## Install on Fedora + +If you are running Fedora Linux, you can install PySCF as a +distribution package, +```bash +dnf install python3-pyscf +``` + +If you are running on an x86-64 platform, dnf should automatically +install the optimized integral library, qcint, instead of the +cross-platform libcint library. + + + +## Docker image + +The following command starts a container with a jupyter notebook +server that listens for HTTP connections on port 8888, +``` +docker run -it -p 8888:8888 pyscf/pyscf:latest +``` + +Now you can visit ``https://localhost:8888`` with your browser to use +PySCF in the notebook. + +Another way to use PySCF in a docker container is to start an Ipython +shell, +```bash +docker run -it pyscf/pyscf:latest start.sh ipython +``` + +## Advanced build options + +### CMake options + +A full build of PySCF may take a long time to finish, and the CMake options +listed below can be used to speed up compilation or omit packages that fail to compile +(e.g., `XCFun` may fail to build if a proper C++ compiler is not available). + +:::{warning} + +If both `-DENABLE_LIBXC=OFF` and `-DENABLE_XCFUN=OFF` are set, importing the +dft module will lead to an `ImportError`. + +::: + +| Flags | Default | Comments +| -------------------- | ------- | ----------------------------------------------------------------- | +| `ENABLE_LIBXC` | ON | Whether to use `Libxc` library in PySCF. If `-DENABLE_LIBXC=OFF` is appended to cmake command, `Libxc` will not be compiled. | +| `ENABLE_XCFUN` | ON | Whether to use `XCFun` library in PySCF. If `-DENABLE_XCFUN=OFF` is appended to cmake command, `XCFun` will not be compiled. | +| `BUILD_LIBXC` | ON | Set it to `OFF` to skip compiling `Libxc`. The dft module still calls `Libxc` library by default. The dft module will be linked against the `Libxc` library from an earlier build. | +| `BUILD_XCFUN` | ON | Set it to `OFF` to skip compiling `XCFun`. The dft module will be linked against the `XCFun` library from an earlier build. | +| `BUILD_LIBCINT` | ON | Set it to `OFF` to skip compiling `libcint`. The integral library from an earlier build will be used. | +| `WITH_F12` | ON | Whether to compile the F12 integrals. | +| `DISABLE_DFT` | OFF | Set this flag to skip the entire dft module. Neither `Libxc` nor `XCFun` will be compiled. | +| `BUILD_MARCH_NATIVE` | OFF | Whether to let the compiler optimize the code against CPU architecture. | + +#### CMake config file + +CMake options can be saved in a configuration file `pyscf/lib/cmake.arch.inc`. +The settings in this file will be automatically loaded and overwrite the +default CMake options during compilation. For example, you can set +`CMAKE_C_FLAGS` in this file to include advanced compiler optimiztion flags, +```bash +set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -ffast-math -mtune=native -march=native") +``` + +Other settings, variables, and flags can also be set in this file, +```bash + set(ENABLE_XCFUN Off) + set(WITH_F12 Off) +``` +Some examples of platform-specific configurations can be found in the +[cmake_user_inc_examples](https://github.com/pyscf/pyscf/tree/master/pyscf/lib/cmake_user_inc_examples) +directory. + + +### Environment variables and global configurations + +| Env variable | Comment | +| ------------------- | ---------------------------------------------------- | +| `PYSCF_MAX_MEMORY` | Maximum memory to use in MB | +| `PYSCF_TMPDIR` | Directory for temporary files | +| `PYSCF_CONFIG_FILE` | File where various PySCF default settings are stored | +| `PYSCF_EXT_PATH` | Path for finding external extensions | + +`PYSCF_MAX_MEMORY` sets the default maximum memory in MB when creating +`Mole` (or `Cell`) object. It corresponds to the attribute +`max_memory``of Mole` (or `Cell`) object. + +The environment variable `PYSCF_TMPDIR` controls which directory is +used to store intermediate files and temporary data when PySCF is run; +it is also commonly known as the scratch directory. If this +environment variable is not set, the system-wide temporary directory +`TMPDIR` will be used as the temp directory, instead. It is highly +recommended to set this variable to a directory with enough disk +space, as many quantum chemistry methods may consume a huge amount of +temporary storage space. It is equally important that the scratch +directory has fast i/o: for instance, using a network-mounted scratch +disk is often much slower than local disks. + +`PYSCF_CONFIG_FILE` is a Python file that can be used to predefine and +override several default parameters in the program: you may already +have noticed statements like `getattr(__config__, "FOOBAR")` many +places in the source code. These global parameters are defined in +`PYSCF_CONFIG_FILE` and loaded when the pyscf module is imported. By +default, this environment variable points to `~/.pyscf_conf.py`. + +`PYSCF_EXT_PATH` allows PySCF to find any possible extension +packages. This is documented in detail in :ref:`installing_extproj`. + +### Install without internet + +In typical installations, all external libraries (libcint, Libxc, XCFun) are +downloaded and installed when the C extensions are compiled, thus requiring +internet access. In this section, we show how to install the external libraries +without internet access, assuming you have downloaded the libcint, Libxc, and +XCFun libraries, +```bash +git clone https://github.com/sunqm/libcint.git +tar czf libcint.tar.gz libcint +wget https://gitlab.com/libxc/libxc/-/archive/6.0.0/libxc-6.0.0.tar.gz +wget -O xcfun.tar.gz https://github.com/fishjojo/xcfun/archive/refs/tags/cmake-3.5.tar.gz +``` + +Assuming `/opt` is the place where these libraries will be installed, they +can be compiled, +```bash +tar xvzf libcint.tar.gz +cd libcint +mkdir build && cd build +cmake -DWITH_F12=1 -DWITH_RANGE_COULOMB=1 -DWITH_COULOMB_ERF=1 \ + -DCMAKE_INSTALL_PREFIX:PATH=/opt -DCMAKE_INSTALL_LIBDIR:PATH=lib .. +make && make install + +tar xvzf libxc-6.0.0.tar.gz +cd libxc-6.0.0 +mkdir build && cd build +cmake -DCMAKE_BUILD_TYPE=RELEASE -DBUILD_SHARED_LIBS=1 \ + -DENABLE_FORTRAN=0 -DDISABLE_KXC=0 -DDISABLE_LXC=1 \ + -DCMAKE_INSTALL_PREFIX:PATH=/opt -DCMAKE_INSTALL_LIBDIR:PATH=lib .. +make && make install + +tar xvzf xcfun.tar.gz +cd xcfun-cmake-3.5 +mkdir build && cd build +cmake -DCMAKE_BUILD_TYPE=RELEASE -DBUILD_SHARED_LIBS=1 -DXCFUN_MAX_ORDER=3 -DXCFUN_ENABLE_TESTS=0 \ + -DCMAKE_INSTALL_PREFIX:PATH=/opt -DCMAKE_INSTALL_LIBDIR:PATH=lib .. +make && make install +``` + +Next, compile PySCF, +```bash +cd pyscf/pyscf/lib +mkdir build && cd build +cmake -DBUILD_LIBCINT=0 -DBUILD_LIBXC=0 -DBUILD_XCFUN=0 -DCMAKE_INSTALL_PREFIX:PATH=/opt .. +make +``` + +Finally, update the ``PYTHONPATH`` environment variable so that the Python +interpreter can find your installation of PySCF. + + +### Using optimized BLAS + +The default installation tries to find the BLAS libraries +automatically. This automated setup script may end up linking the code +to slow versions of BLAS libraries, like the reference NETLIB +implementation. Using an optimized linear algebra library like ATLAS, +BLIS, or OpenBLAS may speed up certain parts of PySCF by factors of 10 to 1000. + +You can compile PySCF against BLAS libraries from other vendors to +improve performance. For example, the Intel Math Kernel Library (MKL) +can provide a 10x speedup in many modules, +```bash +cd pyscf/lib/build +cmake -DBLA_VENDOR=Intel10_64lp_seq .. +make +``` + +When linking the program to MKL, CMake may have problems finding the +correct MKL libraries for some versions of MKL. Setting +``LD_LIBRARY_PATH`` to include the MKL dynamic libraries can sometimes +help, for example, +```bash +export LD_LIBRARY_PATH=/opt/intel/compilers_and_libraries_2018/linux/mkl/lib/intel64:$LD_LIBRARY_PATH +``` + +If you are using Anaconda, you can link PySCF to the MKL library shipped with Anaconda, +```bash +export MKLROOT=/path/to/anaconda2 +export LD_LIBRARY_PATH=$MKLROOT/lib:$LD_LIBRARY_PATH +cd pyscf/lib/build +cmake -DBLA_VENDOR=Intel10_64lp_seq .. +make +``` + +You can also link to other BLAS libraries by setting `BLA_VENDOR`, +e.g., `BLA_VENDOR=ATLAS`, `BLA_VENDOR=IBMESSL`, +`BLA_VENDOR=OpenBLAS` (requiring cmake-3.6). Please refer to the +[CMake manual](http://www.cmake.org/cmake/help/v3.6/module/FindBLAS.html>) +for more details on the use of the `FindBLAS` macro. + +If setting the CMake `BLA_VENDOR` variable does not result in the +right BLAS library being chosen, you can specify the BLAS libraries to +use by hand by setting the `BLAS_LIBRARIES` CMake argument, +```bash +cmake -DBLAS_LIBRARIES=-lopenblaso .. +``` + +You can also hardcode the libraries you want to use in the file `lib/CMakeLists.txt`, +```bash +set(BLAS_LIBRARIES "${BLAS_LIBRARIES};/path/to/mkl/lib/intel64/libmkl_intel_lp64.so") +set(BLAS_LIBRARIES "${BLAS_LIBRARIES};/path/to/mkl/lib/intel64/libmkl_sequential.so") +set(BLAS_LIBRARIES "${BLAS_LIBRARIES};/path/to/mkl/lib/intel64/libmkl_core.so") +set(BLAS_LIBRARIES "${BLAS_LIBRARIES};/path/to/mkl/lib/intel64/libmkl_avx.so") +``` + +:::{note} +The MKL library may lead to an OSError at runtime, +```bash +OSError: ... mkl/lib/intel64/libmkl_avx.so: undefined symbol: ownLastTriangle_64fc +``` +or +```bash +MKL FATAL ERROR: Cannot load libmkl_avx.so or libmkl_def.so +``` +This can be solved by preloading the MKL core library, +```bash +export LD_PRELOAD=$MKLROOT/lib/intel64/libmkl_avx.so:$MKLROOT/lib/intel64/libmkl_core.so +``` +::: + +### Using the Qcint optimized integral library + +The default integral library used by PySCF is +[libcint](https://github.com/sunqm/libcint), which is implemented within a +model that maximizes its compatibility with various high-performance +computing systems. However, on x86-64 platforms, libcint has a more +efficient counterpart, [Qcint](https://github.com/sunqm/qcint), which is +heavily optimized with x86 SIMD instructions (AVX-512/AVX2/AVX/SSE3). +To replace the default libcint library with the qcint library, edit the +URL of the integral library in `lib/CMakeLists.txt` file, +```{code-block} bash +:caption: lib/CMakeLists.txt + +ExternalProject_Add(libcint + GIT_REPOSITORY + https://github.com/sunqm/qcint.git + ... +``` diff --git a/source/user/pbcgto.md b/source/user/pbcgto.md new file mode 100644 index 000000000..3bd467cf0 --- /dev/null +++ b/source/user/pbcgto.md @@ -0,0 +1,220 @@ +# Crystal structure + +**Module**: `pyscf.pbc.gto` + +**Examples**: [pyscf/examples/pbc](https://github.com/pyscf/pyscf/tree/master/examples/pbc) + +## Building a crystal + +Periodic crystals are built using the `pbc.gto.Cell` class, +which is very similar to the `gto.Mole` class, +```python +from pyscf.pbc import gto +cell = gto.Cell() +cell.atom = '''H 0 0 0; H 1 1 1''' +cell.basis = 'gth-dzvp' +cell.pseudo = 'gth-lda' +cell.a = numpy.eye(3) * 2 +cell.build() +``` + +The other equivalent ways to build a molecule introduced in [Molecular +structure](gto), including the shortcut functions `pbc.gto.M()` or `pyscf.M()`, +also apply here, +```python +from pyscf.pbc import gto +cell = gto.Cell() +cell.build( + atom = '''H 0 0 0; H 1 1 1''', + basis = 'gth-dzvp', + pseudo = 'gth-lda', + a = numpy.eye(3) * 2) +``` +```python +from pyscf.pbc import gto +cell = gto.M( + atom = '''H 0 0 0; H 1 1 1''', + basis = 'gth-dzvp', + pseudo = 'gth-lda', + a = numpy.eye(3) * 2) +``` +```python +import pyscf +cell = pyscf.M( + atom = '''H 0 0 0; H 1 1 1''', + basis = 'gth-dzvp', + pseudo = 'gth-lda', + a = numpy.eye(3) * 2) +``` + +## Geometry and lattice vectors + +The `Cell.atom` attribute defines the positions of the atoms inside the unit cell, and +the additional parameter `Cell.a` defines the lattice vectors. +The format of `Cell.a` is array-like, +```python +cell.a = numpy.eye(3) * 2 +cell.a = [[2,0,0],[0,2,0],[0,0,2]] +``` + +Each row of the 3-by-3 matrix of `Cell.a` represents a lattice vector +in Cartesian coordinates, with the same unit as the input `atom` parameter +(and controllable by the `unit` attribute). + +:::{warning} + +The input lattice vectors should form a right-handed coordinate system, as +otherwise some integrals may be computed incorrectly in PySCF. +PySCF will print a warning if the lattice vectors do not form a right-handed +coordinate system. + +::: + +## Basis set and pseudopotentials + +PySCF uses crystalline Gaussian-type orbitals as basis functions for periodic +calculations. The predefined basis sets and ECPs for molecular calculations +can be used in periodic calculations as well. + +As described more in [](link), many PBC calculations require the use of +ECPs (or pseudopotentials, as they are more commonly called in periodic codes). +In addition to molecular ECPs, PySCF includes GTH pseudopotentials, +which have been parameterized for use with HF or different DFT functionals, +```python +cell.pseudo = 'gth-hf' +cell.pseudo = 'gth-lda' # an alias for 'gth-pade' +cell.pseudo = 'gth-pbe' +``` +The GTH pseudopotentials should always be used with corresponding valence basis sets, +```python +cell.basis = 'gth-szv' # or gth-dzv, gth-dzvp, gth-tzvp +``` + +Lists of all available GTH pseudopotentials and basis sets are available in +[pbc/gto/pseudo](https://github.com/pyscf/pyscf/tree/master/pyscf/pbc/gto/pseudo) +and [pbc/gto/basis](https://github.com/pyscf/pyscf/tree/master/pyscf/pbc/gto/basis). + +:::{note} + +GTH basis sets and pseudopotentials are not available for all atoms of the periodic table. + +::: + +## K-points + +The k-points to be used in solid calculations can be obtained through the +`Cell.make_kpts` method, by specifying the number of k-points +in each lattice vector direction, +```python +kpts = cell.make_kpts([1,2,2]) +print(kpts.shape) +# (4,3) +``` +By default, this will return the shifted Monkhorst-Pack mesh that includes +the Gamma point. To get the non-shifted Monkhorst-Pack mesh, +```python +kpts = cell.make_kpts([1,2,2], with_gamma_point=False) +``` + +To get a shifted Monkhorst-pack mesh centered at a specific point, +```python +kpts = cell.make_kpts([1,2,2], scaled_center=[0.,0.25,0.25]) +``` +where `scaled_center` is defined in the units of reciprocal lattice vectors. + +The obtained k-points are used as input for crystalline electronic structure calculations, +```python +from pyscf.pbc import scf +kpts = cell.make_kpts([2,2,2]) +kmf = scf.KRHF(cell, kpts=kpts) +e_hf = kmf.kernel() +``` + +Calculations with k-points always return the energy per unit cell. + +## Spin + +Because k-point sampling formally represents a calculation on a supercell, +the attribute `Cell.spin` indicates the number of unpaired electrons in the +supercell (**not** in the unit cell). For example, in a calculation with +a 2x2x2 k-point mesh, `cell.spin = 1` leads to one unpaired electron in the +supercell (not eight). + +## Low-dimensional systems + +The PySCF `pbc` module also supports low-dimensional periodic systems. You can initialize +the attribute `Cell.dimension` to specify the dimension of the system, +```python +cell.dimension = 2 +cell.a = numpy.eye(3) * 2 +cell.build() +``` + +When `Cell.dimension` is smaller than 3, a vacuum of infinite size will be +applied in certain direction(s). For example, when `Cell.dimension = 2`, +the z-direction will be treated as infinitely large and the xy-plane +constitutes the periodic surface. When `Cell.dimension = 1`, the y and z axes +are treated as vacuum and thus the system is a wire in the x direction. +When `Cell.dimension = 0`, all three directions are treated as vacuum, and this is +equivalent to a molecular system. + +## Other parameters + +The `Cell.precision` attribute determines the integral accuracy, and its +default value is `1e-8` hartree. When calling the `cell.build()` method, +some parameters are set automatically based on the value of `precision`, including + + * `mesh` - length-3 list or 1x3 array of int + + - The numbers of grid points in the FFT-mesh in each direction. + + * `ke_cutoff` - float + + - Kinetic energy cutoff of the plane waves in FFTDF + + * `rcut` - float + + - Cutoff radius (in Bohr) of the lattice summation in the integral evaluation + +Other attributes of the `Mole` class such as `verbose`, +`max_memory`, etc., have the same meanings in the `Cell` class. + +:::{note} + +Currently, point group symmetries for crystals are not supported. + +::: + +## Accessing AO integrals + +Periodic AO integrals can be evaluated using the `Cell.pbc_intor` function, +```python +overlap = cell.pbc_intor('int1e_ovlp') +kin = cell.pbc_intor('int1e_kin') +``` + +By default, the `Cell.pbc_intor` function only returns integrals at the +Gamma point. If k-points are specified, it will return the integrals at each +k-point, +```python +kpts = cell.make_kpts([2,2,2]) +overlap = cell.pbc_intor('int1e_ovlp', kpts=kpts) +``` + +:::{note} + +The `Cell.pbc_intor` function can only be used to evaluate periodic short-range +integrals. PBC density fitting methods have to be used to compute the integrals for +long-range operators such as the electron-nuclear attraction and the electron-electron +repulsion integrals. + +::: + +The electron repulsion integrals can be evaluated with the periodic density fitting +methods, +```python +from pyscf.pbc import df +eri = df.DF(cell).get_eri() +``` +See [Periodic density fitting](pbc/df) for more details. + diff --git a/source/user/using.md b/source/user/using.md new file mode 100644 index 000000000..e2285af10 --- /dev/null +++ b/source/user/using.md @@ -0,0 +1,281 @@ +# How to use PySCF + +This page provides an introduction to the generic organization of PySCF +and typical workflows. + +## Modules, classes, and the kernel method + +Similar to [NumPy](https://numpy.org/) or [SciPy](https://scipy.org/), PySCF is +a collection of modules, such as `gto` (for defining molecules with Gaussian type orbitals), +`scf` (for self-consistent field calculations), or `cc` (for coupled-cluster calculations). +Modules must be imported to be used, +```python +from pyscf import gto, scf, cc +``` + +Modules provide access to both functions and classes, where the latter is more commonly +used to define a calculation. For example, the `gto` module provides the `gto.Mole` class, +the `scf` module provides the `scf.RHF` class (and others, such as `scf.UHF`, etc.), and +the `cc` module provides the `cc.CCSD` class. + +Performing a calculation in PySCF typically involves +importing a module, instantiating a class provided by that module with some arguments, +and executing the functions of that class. For example, +```python +from pyscf import scf # import module +myhf = scf.RHF(...) # instantiate class +e_hf = myhf.kernel() # execute kernel() method to do the calculation +``` + +Every class has the `kernel()` method, which serves as the driver of +the calculation, although many classes provide an alias to the `kernel()` method, +such as the `build()` method of the `gto.Mole` class. + +Once an object is created, you can always call `kernel()` to start or restart +a calculation. The return value of the kernel method depends on the class. + +The instance of one class is commonly passed as an argument to instantiate the +next class in a workflow. For example, the instance of the molecular structure +class is passed to instantiate a Hartree-Fock class, whose instance is passed +to instantiate a coupled-cluster class, +```python +from pyscf import gto, scf, cc +mymol = gto.Mole(...) +mymol.build() # returns mymol +myscf = scf.RHF(mymol) +e_hf = mymol.kernel() +mycc = cc.CCSD(myscf) +e_corr, t1, t2 = mycc.kernel() +``` + +Chained calculations, like the one above, can also be performed more concisely +using [Stream methods](#stream-methods) or [Scanners](#scanners), as described +in the following sections. + +## Stream methods + +To unify the return value of different methods and thus allow chaining calculations together, +PySCF includes three "stream methods". A stream method of an object only returns the object +itself. The three stream methods are described below. + +1. The `set` method updates object attributes. For example, + ```python + mf = scf.RHF(mol).set(conv_tol=1e-5) + ``` + is identical to two lines of statements, + ```python + mf = scf.RHF(mol) + mf.conv_tol = 1e-5 + ``` + +2. The `run` method calls the `kernel` method. Arguments passed to the + `run` method will be passed to the kernel method. If keyword arguments are + given, `run` will first call the `set` method to update the attributes and + then execute the `kernel` method. For example, + ```python + mf = scf.RHF(mol).run(dm_init, conv_tol=1e-5) + ``` + is identical to three lines of statements, + ```python + mf = scf.RHF(mol) + mf.conv_tol = 1e-5 + mf.kernel(dm_init) + ``` + +3. The `apply` method passes the current object (as the first argument) to the + given function/class and returns a new object. If arguments and keyword + arguments are given, they will all be passed to the function/class. For + example, + ```python + mc = mol.apply(scf.RHF).run().apply(mcscf.CASSCF, 6, 4, frozen=4) + ``` + is identical to, + ```python + mf = scf.RHF(mol) + mf.kernel() + mc = mcscf.CASSCF(mf, 6, 4, frozen=4) + ``` + Note that the `apply()` method does not call the `kernel()` method. + +In addition to these three stream methods, many regular class methods also +return the object (especially those that do not have any particular values to +return). Such methods can therefore be used in streams. For +example, +```python +dm = gto.M(atom='H 0 0 0; H 0 0 1') \ + .apply(scf.RHF) \ + .dump_flags() \ + .run() \ + .make_rdm1() +``` +This code works because the `dump_flags()` method simply prints information and then +returns the object. + +## Scanners + +A scanner is a function that takes a `Mole` (or `Cell`) object as input and +returns the energy or nuclear gradients at a chosen level of theory. A scanner +can be considered as a shortcut function for a sequence of statements, which +includes the initialization of a required calculation model with possible +precomputing, updating the attributes based on the settings of the referred +object, calling the kernel function, and finally returning results. + +For example, consider the following conventional script to perform a potential +energy surface scan of the dissociation of the hydrogen molecule using CCSD, +```python +for r in (1.0, 1.1, 1.2): + mol = gto.M(atom=f"H 0 0 0; H 0 0 {r}") + mf = scf.RHF(mol).run() + mycc = cc.CCSD(mf).run() + print(mycc.e_tot) +``` + +This can be simplified using the `as_scanner()` method, +```python +cc_scanner = gto.M().apply(scf.RHF).apply(cc.CCSD).as_scanner() +for r in (1.0, 1.1, 1.2): + print(cc_scanner(gto.M(atom=f"H 0 0 0; H 0 0 {r}"))) +``` + +There are two types of scanners available in the package: energy scanners and +nuclear gradients scanners. An energy scanner, like the example above, only +returns the energy of the given molecular structure while the nuclear gradients +scanner returns the nuclear gradients. + +A scanner is a special derived object of the calling class. Most methods that are +defined in the calling are also accessible through the scanner object. For example, +```python +mf_scanner = gto.M().apply(scf.RHF).as_scanner() +mf_scanner(gto.M(atom='H 0 0 0; H 0 0 1.2')) +mf_scanner.analyze() +dm1 = mf_scanner.make_rdm1() + +mf_grad_scanner = mf_scanner.nuc_grad_method().as_scanner() +mf_grad_scanner(gto.M(atom='H 0 0 0; H 0 0 1.2')) +``` +As shown in this example, the scanner behaves very similarly to an RHF +class object, except that the scanner does not need the `kernel` or `run` +methods to run a calculation. Given a molecule structure, the scanner +automatically checks and updates the necessary object dependencies and passes the +work flow to the `kernel` method. The computational results are held in the +scanner object the same way as in the regular class object. + +To make the behavior of scanner objects uniform for all levels of theory, +two attributes (`e_tot` and `converged`) are defined for all energy scanners, +and three attributes (`e_tot`, `de`, and `converged`) are defined for +all nuclear gradients scanners. + + + +## Class and function behaviors + +Classes are designed to hold only the final results (such as energies and wavefunction parameters) +and the control parameters (such as the convergence threshold and the maximum number of iterations). +Intermediate quantities are **not** saved in the class. + +After calling the `kernel()` or `run()` method, results will be generated and +saved as attributes of the object. For example, +```python +from pyscf import gto, scf, ccsd +mol = gto.M(atom='H 0 0 0; H 0 0 1.1', basis='ccpvtz') +mf = scf.RHF(mol).run() +mycc = ccsd.CCSD(mf).run() +print(mycc.e_tot) +print(mycc.e_corr) +print(mycc.t1.shape) +print(mycc.t2.shape) +``` + +Many useful functions are defined at both the class level (as methods) and +the module level. For example, +```python +myhf = scf.RHF(mol) +vj, vk = myhf.get_jk(mol, dm) # class method +vj, vk = scf.hf.get_jk(mol, dm) # module function +``` +Note that some module functions may require the class object as the first argument, +```python +e_hf = myhf.kernel(conv_tol=1e-5) # class method +e_hf = scf.hf.kernel(mymf, conv_tol=1e-5) # module function +``` + +In PySCF, most functions and classes are **pure**, which means that no +intermediate status is held within the classes, and the arguments of the +methods and functions are immutable during calculations. Pure functions can be +called any number of times in arbitrary order and their return values should +always be the same. + +:::{warning} + + Exceptions to "pure" function behavior are often indicated with an underscore at the +end of the function name, +```python +mcscf.state_average_(mc) +# the attributes of the mc object may be changed +# or overwritten by state_average_ +``` +Be careful when you see functions or methods ending with an underscore! + +::: + +## Global configurations + +Default behaviors in PySCF can be controlled by using global configurations. +A global configuration file is a Python script that contains PySCF configurations. +When PySCF is imported in a Python program (or Python interpreter), the +package will preload the global configuration file to set default values. +For example, the configuration file below detects the available memory in the +operating system at runtime and sets the maximum memory for PySCF, +```{code-block} python +:caption: ~/.pyscf_conf.py + +import psutil +MAX_MEMORY = int(psutil.virtual_memory().available / 1e6) +``` + +By setting `MAX_MEMORY` in the global configuration file, you don't need to set +the `max_memory` attribute in every script. The dynamically determined +`MAX_MEMORY` will be loaded during the program initialization automatically. + +There are two ways to identify a global configuration file. +The first is to create a configuration file `.pyscf_conf.py` in your home directory or +in the current working directory. The second is to set the environment variable +`PYSCF_CONFIG_FILE` to the configuration file (absolute) path. +The environment variable `PYSCF_CONFIG_FILE` has higher priority than +the configuration file found in the home or working directories. +If the environment variable `PYSCF_CONFIG_FILE` is available, PySCF will +use its configurations. If `PYSCF_CONFIG_FILE` is not set or the file it points +to does not exist, PySCF will look for the file `.pyscf_conf.py` in the +home and working directories. If no configuration file is found, PySCF +will use the built-in configurations which are generally conservative. + +Global configurations are set in the `pyscf.__config__` module, which +is then imported and used by PySCF, +```python +from pyscf import __config__ +MAX_MEMORY = getattr(__config__, 'MAX_MEMORY') +``` + +Available configurations can be found by reading the source code of PySCF +and its modules. For example, generic configuration parameters include `DEBUG`, `MAX_MEMORY`, +`TMPDIR`, `ARGPARSE`, `VERBOSE`, and `UNIT`, and specific configuration parameters +for a Hartree-Fock calculation can be found at the top of the file, +```{code-block} python +:caption: pyscf/scf/hf.py + +from pyscf import __config__ + +WITH_META_LOWDIN = getattr(__config__, 'scf_analyze_with_meta_lowdin', True) +PRE_ORTH_METHOD = getattr(__config__, 'scf_analyze_pre_orth_method', 'ANO') +MO_BASE = getattr(__config__, 'MO_BASE', 1) +TIGHT_GRAD_CONV_TOL = getattr(__config__, 'scf_hf_kernel_tight_grad_conv_tol', True) +MUTE_CHKFILE = getattr(__config__, 'scf_hf_SCF_mute_chkfile', False) +``` +For example, you can choose to change the default behavior associated with the use of +meta Lowdin population analysis, +```{code-block} python +:caption: ~/.pyscf_conf.py + +scf_analyze_with_meta_lowdin = False +``` +