From 9dcead57eaf6c5474ca0429f7dd76cf73b739807 Mon Sep 17 00:00:00 2001 From: Timothy Berkelbach Date: Wed, 19 Jun 2024 13:50:36 -0400 Subject: [PATCH 01/12] Update README about gh-pages deployment and remove unused Slack workflow --- .github/workflows/slack_notification.yaml | 21 ------------ README.md | 41 ++++------------------- 2 files changed, 6 insertions(+), 56 deletions(-) delete mode 100644 .github/workflows/slack_notification.yaml 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..32a5cbda6 100644 --- a/README.md +++ b/README.md @@ -59,45 +59,16 @@ 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 - -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: - -```bash -make gh_pages_setup -``` +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. ## 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). - - - From 8181c6cfa07944a4189a30170aa4fa5bf41ec042 Mon Sep 17 00:00:00 2001 From: Timothy Berkelbach Date: Wed, 19 Jun 2024 14:24:12 -0400 Subject: [PATCH 02/12] Change to PyData Sphinx Theme --- requirements.txt | 4 + .../css/{pyscf.css => pyscf-material.css} | 0 source/_static/css/pyscf-pst.css | 14 + source/conf.py | 281 +++++------------- 4 files changed, 98 insertions(+), 201 deletions(-) rename source/_static/css/{pyscf.css => pyscf-material.css} (100%) create mode 100644 source/_static/css/pyscf-pst.css diff --git a/requirements.txt b/requirements.txt index b997ce7e8..7f32f14ac 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,3 +7,7 @@ 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/conf.py b/source/conf.py index 5789ab628..b6713a324 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,84 @@ # -- 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", + }, + "show_toc_level": 1, + "use_edit_page_button": True, + "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 +200,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. From 9da27b8a7b76b6ee1216ea5d6245309e0e4a1434 Mon Sep 17 00:00:00 2001 From: Timothy Berkelbach Date: Wed, 19 Jun 2024 14:56:04 -0400 Subject: [PATCH 03/12] Update home page and overall organization --- source/conf.py | 2 +- .../agf2_developer.rst | 0 .../ao2mo_developer.rst | 0 .../{develop => contributor}/cc_developer.rst | 0 .../{develop => contributor}/ci_developer.rst | 0 source/{develop => contributor}/cisd.rst | 0 .../code-standard.rst} | 0 .../{develop => contributor}/df_developer.rst | 0 .../dft_developer.rst | 0 .../eph_developer.rst | 0 .../fci_developer.rst | 0 .../gto_developer.rst | 0 source/contributor/index.md | 11 + .../mcscf_developer.rst | 0 .../pbc_developer.rst | 0 .../scf_developer.rst | 0 .../soscf_developer.rst | 0 source/{develop => contributor}/table.png | Bin .../tdscf_developer.rst | 0 source/index.md | 49 ++++ source/index.rst | 58 ----- source/tools/extensions/gallery_directive.py | 145 ++++++++++++ source/user.rst | 38 --- source/user/extensions.md | 106 +++++++++ source/user/index.md | 62 +++++ source/user/pbcgto.md | 220 ++++++++++++++++++ 26 files changed, 594 insertions(+), 97 deletions(-) rename source/{develop => contributor}/agf2_developer.rst (100%) rename source/{develop => contributor}/ao2mo_developer.rst (100%) rename source/{develop => contributor}/cc_developer.rst (100%) rename source/{develop => contributor}/ci_developer.rst (100%) rename source/{develop => contributor}/cisd.rst (100%) rename source/{code-rule.rst => contributor/code-standard.rst} (100%) rename source/{develop => contributor}/df_developer.rst (100%) rename source/{develop => contributor}/dft_developer.rst (100%) rename source/{develop => contributor}/eph_developer.rst (100%) rename source/{develop => contributor}/fci_developer.rst (100%) rename source/{develop => contributor}/gto_developer.rst (100%) create mode 100644 source/contributor/index.md rename source/{develop => contributor}/mcscf_developer.rst (100%) rename source/{develop => contributor}/pbc_developer.rst (100%) rename source/{develop => contributor}/scf_developer.rst (100%) rename source/{develop => contributor}/soscf_developer.rst (100%) rename source/{develop => contributor}/table.png (100%) rename source/{develop => contributor}/tdscf_developer.rst (100%) create mode 100644 source/index.md delete mode 100644 source/index.rst create mode 100644 source/tools/extensions/gallery_directive.py delete mode 100644 source/user.rst create mode 100644 source/user/extensions.md create mode 100644 source/user/index.md create mode 100644 source/user/pbcgto.md diff --git a/source/conf.py b/source/conf.py index b6713a324..418149cd7 100644 --- a/source/conf.py +++ b/source/conf.py @@ -29,7 +29,7 @@ "pyscfdocext", "myst_parser", "sphinx_design", -# "gallery_directive", + "gallery_directive", ] bibtex_bibfiles = ['user/ref.bib'] myst_update_mathjax = False 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/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. + From 873264e5a1ef35cd925cec043642af612901e1c8 Mon Sep 17 00:00:00 2001 From: Timothy Berkelbach Date: Wed, 19 Jun 2024 16:01:06 -0400 Subject: [PATCH 04/12] Add updated How to install and How to use pages to User Guide --- source/user/install.md | 374 +++++++++++++++++++++++++++++++++++++++++ source/user/using.md | 278 ++++++++++++++++++++++++++++++ 2 files changed, 652 insertions(+) create mode 100644 source/user/install.md create mode 100644 source/user/using.md diff --git a/source/user/install.md b/source/user/install.md new file mode 100644 index 000000000..5199db880 --- /dev/null +++ b/source/user/install.md @@ -0,0 +1,374 @@ +# 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 +``` + +:::{note} +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, +```bash +ExternalProject_Add(libcint + GIT_REPOSITORY + https://github.com/sunqm/qcint.git + ... +``` diff --git a/source/user/using.md b/source/user/using.md new file mode 100644 index 000000000..e47a73e35 --- /dev/null +++ b/source/user/using.md @@ -0,0 +1,278 @@ +# 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 +operate system at the runtime and set the maximum memory for PySCF, +```python +# this is the global configuration file ~/.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, +```python +# this is 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, +```python +# this is ~/.pyscf_conf.py +scf_analyze_with_meta_lowdin = False +``` + From c01b7fda54e5a81061c9acca1411a43b08d3dcc5 Mon Sep 17 00:00:00 2001 From: Timothy Berkelbach Date: Wed, 19 Jun 2024 16:01:22 -0400 Subject: [PATCH 05/12] Add GitHub link --- source/conf.py | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/source/conf.py b/source/conf.py index 418149cd7..96d4414cb 100644 --- a/source/conf.py +++ b/source/conf.py @@ -175,8 +175,16 @@ "image_light": "../logo/logo-64x64.png", "image_dark": "../logo/logo-64x64.png", }, - "show_toc_level": 1, + "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"], }, From b0f8ff9687c30fe7689b7c734fde11e370443b58 Mon Sep 17 00:00:00 2001 From: Timothy Berkelbach Date: Wed, 19 Jun 2024 16:11:31 -0400 Subject: [PATCH 06/12] Edit How to use page --- source/user/using.md | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/source/user/using.md b/source/user/using.md index e47a73e35..3926c3dc9 100644 --- a/source/user/using.md +++ b/source/user/using.md @@ -22,9 +22,9 @@ 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 +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 @@ -41,7 +41,7 @@ to instantiate a coupled-cluster class, ```python from pyscf import gto, scf, cc mymol = gto.Mole(...) -mymol.build() # returns mymol +mymol.build() # returns mymol myscf = scf.RHF(mymol) e_hf = mymol.kernel() mycc = cc.CCSD(myscf) @@ -190,13 +190,13 @@ 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 +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 +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 @@ -225,9 +225,10 @@ A global configuration file is a Python script that contains PySCF configuration 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 -operate system at the runtime and set the maximum memory for PySCF, -```python -# this is the global configuration file ~/.pyscf_conf.py +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) ``` @@ -259,8 +260,9 @@ 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, -```python -# this is scf/hf.py +```{code-block} python +:caption: pyscf/scf/hf.py + from pyscf import __config__ WITH_META_LOWDIN = getattr(__config__, 'scf_analyze_with_meta_lowdin', True) @@ -271,8 +273,9 @@ 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, -```python -# this is ~/.pyscf_conf.py +```{code-block} python +:caption: ~/.pyscf_conf.py + scf_analyze_with_meta_lowdin = False ``` From 59085b1c0d0c0b47dfa139efe0d97d97d2c6c1d1 Mon Sep 17 00:00:00 2001 From: Timothy Berkelbach Date: Wed, 19 Jun 2024 16:13:21 -0400 Subject: [PATCH 07/12] Edit How to use page --- source/user/using.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/user/using.md b/source/user/using.md index 3926c3dc9..e2285af10 100644 --- a/source/user/using.md +++ b/source/user/using.md @@ -108,7 +108,7 @@ dm = gto.M(atom='H 0 0 0; H 0 0 1') \ .run() \ .make_rdm1() ``` -This code works because the `.dump_flags()` method simply prints information and then +This code works because the `dump_flags()` method simply prints information and then returns the object. ## Scanners From 681e95b3c6f29c8792bfbbaa312da6206c396c25 Mon Sep 17 00:00:00 2001 From: Timothy Berkelbach Date: Wed, 19 Jun 2024 16:26:32 -0400 Subject: [PATCH 08/12] Small edit to How to install --- source/user/install.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/source/user/install.md b/source/user/install.md index 5199db880..72049f42c 100644 --- a/source/user/install.md +++ b/source/user/install.md @@ -24,7 +24,7 @@ PySCF via pip, you can upgrade it to the new version, pip install --upgrade pyscf ``` -:::{note} +:::{seealso} Newly introduced features are available in the [pyscf-forge](https://github.com/pyscf/pyscf-forge) package, which can be installed with `pip`, @@ -355,6 +355,7 @@ 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 @@ -365,8 +366,10 @@ 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, -```bash +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 From 738cda0627eafb5c33f3ffd55220de9de21f21ca Mon Sep 17 00:00:00 2001 From: Timothy Berkelbach Date: Wed, 19 Jun 2024 16:27:23 -0400 Subject: [PATCH 09/12] Small edit to How to install --- source/user/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/user/install.md b/source/user/install.md index 72049f42c..a063bd30f 100644 --- a/source/user/install.md +++ b/source/user/install.md @@ -141,7 +141,7 @@ Extension modules are not available in the Fedora package. ## Docker image The following command starts a container with a jupyter notebook -server that listens for HTTP connections on port 8888:: +server that listens for HTTP connections on port 8888, ``` docker run -it -p 8888:8888 pyscf/pyscf:latest ``` From bc301aea874fce306105edb773b4be3e137e8774 Mon Sep 17 00:00:00 2001 From: Timothy Berkelbach Date: Wed, 19 Jun 2024 16:39:42 -0400 Subject: [PATCH 10/12] Update About page --- source/about.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ source/about.rst | 38 -------------------------------------- 2 files changed, 47 insertions(+), 38 deletions(-) create mode 100644 source/about.md delete mode 100644 source/about.rst 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. From 174db61d643bb1a070be0ee717c5215bc63c2140 Mon Sep 17 00:00:00 2001 From: Timothy Berkelbach Date: Thu, 25 Jul 2024 10:37:33 -0400 Subject: [PATCH 11/12] Update README --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 32a5cbda6..fcc89020c 100644 --- a/README.md +++ b/README.md @@ -67,8 +67,10 @@ 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. -## How to Contribute +## 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). +Website pages can be written in Markdown `.md` or reStructuredTest `.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. From bf0cba63dc134858fab44ff8d62cc2832a06acf8 Mon Sep 17 00:00:00 2001 From: Timothy Berkelbach Date: Thu, 25 Jul 2024 10:40:59 -0400 Subject: [PATCH 12/12] Update requirements and README --- README.md | 4 +++- requirements.txt | 2 -- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index fcc89020c..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 diff --git a/requirements.txt b/requirements.txt index 7f32f14ac..69d0f0d2d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,7 +1,5 @@ pyscf sphinx -ablog -sphinx-material sphinxcontrib-bibtex nbsphinx Pygments==2.15.0