From 85928414b94af4d31b05e069df265bbab97fd81e Mon Sep 17 00:00:00 2001 From: Qiming Sun Date: Thu, 9 Jan 2025 08:05:32 -0800 Subject: [PATCH] Documents for pyscf-forge and extensions --- source/extensions.rst | 83 ++++++++++++++++++++++++++++++++++++++++++ source/install.rst | 24 ++++++++++-- source/pyscf-forge.rst | 75 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 179 insertions(+), 3 deletions(-) create mode 100644 source/extensions.rst create mode 100644 source/pyscf-forge.rst diff --git a/source/extensions.rst b/source/extensions.rst new file mode 100644 index 00000000..cdff1b02 --- /dev/null +++ b/source/extensions.rst @@ -0,0 +1,83 @@ +.. _extensions_list: + +Extensions and optional dependencies +************************************ + +PySCF is structured into three hierarchical levels of features: core +modules, forge modules, and extensions. In addition, some features are provided +as optional dependencies, enhancing PySCF functionality. + +* **Core Modules**: These modules provide fundamental functionalities such as + basic DFT computations and integral evaluations. They serve as the + foundational building blocks for other packages and features. The APIs in + these modules are relatively stable, and performance optimization is not the + primary focus. + +* **PySCF Forge**: This repository includes newly developed functionalities that + are in the staging phase. Features in the forge may eventually be integrated + into the core modules. For further details, refer to :ref:`pyscf_forge`. + +* **Extensions**: Extensions are not intended to become part of the core + modules. They are designed to accommodate experimental features, specific + optimizations, or libraries that require complex compilation environments or + dependencies. These extensions rely on the core modules for functionality. The + PySCF organization commits to maintaining these extensions to ensure + compatibility with other components of PySCF. + +* **Optional Dependencies**: Many features and modules are developed by the + community using the PySCF APIs. The key distinction between optional + dependencies and extensions is that the PySCF organization does not maintain + these optional dependencies. + +List of Extensions +================== + +(To be listed here: + Names, brief descriptions, and installation instructions) + +Summary +------- + +=================== ========================================================= +Project URL +=================== ========================================================= +cornell-shci https://github.com/pyscf/cornell-shci +dispersion https://github.com/pyscf/dispersion +dmrgscf https://github.com/pyscf/dmrgscf +doci https://github.com/pyscf/doci +fciqmc https://github.com/pyscf/fciqmc +forge https://github.com/pyscf/pyscf-forge +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 +properties https://github.com/pyscf/properties +qsdopt https://github.com/pyscf/qsdopt +rt https://github.com/pyscf/rt +semiempirical https://github.com/pyscf/semiempirical +shciscf https://github.com/pyscf/shciscf +tblis https://github.com/pyscf/pyscf-tblis +gpu4pyscf https://github.com/pyscf/gpu4pyscf +=================== ========================================================= + +List of Optional Dependencies +============================= +(To be listed here: + Names, brief descriptions, and links to the dependencies) + +Summary +------- + +=================== ========================================================= +Project URL +=================== ========================================================= +cas_ac0 https://github.com/CQCL/pyscf-ac0 +ccpy https://github.com/piecuch-group/ccpy +cppe https://github.com/maxscheurer/cppe +ebcc https://github.com/BoothGroup/ebcc +dftd3 https://github.com/dftd3/simple-dftd3 +pyqmc https://github.com/WagnerGroup/pyqmc +zquatev https://github.com/sunqm/zquatev +geometric https://github.com/leeping/geomeTRIC +pyberny https://github.com/jhrmnn/pyberny +=================== ========================================================= diff --git a/source/install.rst b/source/install.rst index f727e0ac..2e8fcc12 100644 --- a/source/install.rst +++ b/source/install.rst @@ -388,8 +388,10 @@ Install PySCF extensions Extension modules ================= -As of PySCF-2.0, some modules have been moved from the main code trunk -to extension projects hosted at https://github.com/pyscf. +As of PySCF-2.0, PySCF has been restructured to simplify the maintanence of the +core modules. Some modules have been relocated from the main codebase to +to extension projects. These projects are hosted at https://github.com/pyscf. + In addition, community-contributed packages that are officially recognized as PySCF extensions are also listed below. @@ -400,7 +402,6 @@ cas_ac0 https://github.com/CQCL/pyscf-ac0 cornell-shci https://github.com/pyscf/cornell-shci ccpy https://github.com/piecuch-group/ccpy cppe https://github.com/maxscheurer/cppe -dftd3 https://github.com/pyscf/dftd3 dispersion https://github.com/pyscf/dispersion dmrgscf https://github.com/pyscf/dmrgscf doci https://github.com/pyscf/doci @@ -418,8 +419,25 @@ 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 +gpu4pyscf https://github.com/pyscf/gpu4pyscf +dispersion https://github.com/pyscf/dispersion =================== ========================================================= +More details of the extensions and optional dependencies can be found in the +:ref:`extensions_list`. + + +Install PySCF-Forge +=================== +Newly developed methods, such as MCPDFT and pp-RPA, are first introduced in PySCF-Forge. +PySCF-Forge is a platform serving as a staging area for features before they are +integrated into the core modules. For more details, see :ref:`pyscf_forge`. + +To access these methods, you need to install PySCF-Forge using the following command: + + $ pip install pyscf-forge + + Install extensions ================== diff --git a/source/pyscf-forge.rst b/source/pyscf-forge.rst new file mode 100644 index 00000000..a93e5d69 --- /dev/null +++ b/source/pyscf-forge.rst @@ -0,0 +1,75 @@ +.. _pyscf_forge: + +PySCF-Forge +*********** + +PySCF-Forge is a platform designed to host innovative methodologies that may +eventually be integrated into the main PySCF core branch. + +Installation +============ +PySCF-forge can be installed via PyPI:: + + $ pip install pyscf-forge + +Alternatively, you can build it from the source code:: + + $ pip install git+https://github.com/pyscf/pyscf-forge + +Using modules in PySCF-Forge +============================ +Once you have installed both PySCF and PySCF-Forge, you can access the features +of PySCF-forge just like the regular features in PySCF, using `from pyscf import +...` statement. Although these source code of the modules are hosted in a +separate repository, they function as part of the PySCF package. + +Please note that the APIs and usage of modules within PySCF-Forge may be subject to +change. Particularly, when a module is transferred from PySCF-Forge to the core +branch, modifications to module names or function APIs may occur. + +Contributing to PySCF-Forge +=========================== +Contributing to the PySCF-Forge repository provides an opportunity for your +methodologies to be reviewed and potentially integrated into the PySCF core +branch. By placing your code into PySCF-forge, +PySCF maintainers will provide feedback and help evaluate the integration +potential of your work. + +It is important to note that not all code submitted to PySCF-Forge will be moved +to the core branch. Such decisions require approval from the board. For a +detailed guide on contributing, please refer to the +[Guidelines](https://github.com/pyscf/pyscf-forge/blob/master/CONTRIBUTING.md). + +How to transfer a feature from forge to core? +============================================= +To ensure a smooth transition of features from PySCF-Forge to the PySCF core +branch, the following steps should be followed: + +* Duration Requirement: A feature must have been part of PySCF-Forge for at + least six months before it can be considered for transfer to the core branch. + This period allows for adequate testing and refinement. + +* Initiating Transfer: Developers who wish to transfer a feature should + open an issue on the PySCF-Forge GitHub repository to request the migration. + This proposal will initiate a discussion in the PySCF board to consider the transfer. + +* Maintenance Commitment: Identify and propose a volunteer who commits to + being responsible for the long-term maintenance of the feature. + +Co-authorship +============= +When a feature is added to the PySCF-forge, it is crucial to recognize the +contributions of individuals. Here are the guidelines for co-authorship in the +context of the PySCF project: + +* Initial Contribution: The original contributor of a feature to the + PySCF-forge is eligible for co-authorship. + +* Long-term Maintenance: Individuals who commit to the long-term + maintenance of the feature also qualify for co-authorship. Their ongoing + efforts to update, optimize, and support the feature are critical. + +* Documentation and Testing: Documenting the feature and creating comprehensive + tests are important to the stability and usability of the feature. + Contributors who play significant roles in these works are qualified for + co-authorship.