Documents for pyscf-forge and extensions

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
+=================== =========================================================

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
 ==================
 

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.