Add pyscf-forge page to user guide

Author: tberkel

source/user/index.md

@@ -55,7 +55,14 @@ gpu.rst
 ```   
 
 ```{toctree}
-:caption: Extensions
+:caption: PySCF-forge 
+:maxdepth: 1
+
+pyscf-forge
+```
+
+```{toctree}
+:caption: Extensions 
 :maxdepth: 1
 
 extensions

source/user/pyscf-forge.md

@@ -0,0 +1,152 @@
+# Overview 
+
+PySCF-forge is a staging ground for new methods or features that are expected
+to be made available in the main PySCF distribution. Not all new features are
+appropriate for PySCF-forge; experimental or niche features are more
+appropriately distributed as [](./extensions).
+
+## How to install PySCF-forge
+
+PySCF-forge is distributed as a 
+[separate GitHub repository](https://github.com/pyscf/pyscf-forge).
+Like PySCF, it can be installed via pip,
+```
+pip install pyscf-forge
+# or
+pip install git+https://github.com/pyscf/pyscf-forge
+```
+or cloned and built from source.  As long as PySCF-forge can be found in your
+`PYTHONPATH`, its modules can be imported as if they were native to PySCF.
+Alternatively, you can define the `PYSCF_EXT_PATH` environment variable to
+point to your local `pyscf-forge` directory,
+```
+export PYSCF_EXT_PATH=/path/to/pyscf-forge
+```
+PySCF will read the `PYSCF_EXT_PATH` environment variable and load modules from
+this path at runtime. For more details of the `PYSCF_EXT_PATH` environment
+variable, see the
+[Extensions](./extensions.md#environment-variable-pyscf-ext-path) section.  For
+example,
+```python
+from pyscf import gto, mcpdft  # mcpdft is in pyscf-forge
+mol = gto.M(
+    atom = 'O 0 0 0; O 0 0 1.2',
+    basis = 'ccpvdz',
+    spin = 2)
+mf = mol.RHF().run ()
+# Calling the MC-PDFT method provided by the pyscf-forge modules
+mc = mcpdft.CASCI(mf, 'tPBE', 6, 8).run()
+```
+
+## How to develop in PySCF-forge 
+
+If you are developing new features or modifying the code in PySCF-forge, an
+editable installation is recommended.  By configuring the package in editable
+mode, you can modify existing modules and add new features to PySCF-forge.
+After cloning the library to your local repository, there are two ways to
+enable the editable installation.
+
+### Method 1. Using pip for editable installation
+
+Install the package with the following pip command,
+```
+pip install --no-deps -e /path/to/pyscf-forge
+```
+This command creates a `.pth` file in `~/.local/lib/python3.*/site-packages/`
+or other Python runtime paths. It is recommended to use this method with Python
+virtual environments.
+
+### Method 2. Setting an environment variable
+
+As described above, you can also define the `PYSCF_EXT_PATH` environment
+variable to point to your local PySCF-forge directory,
+```
+export PYSCF_EXT_PATH=/path/to/pyscf-forge
+```
+
+### Adding new features: An example
+
+Suppose you want to create a new module in PySCF-forge that provides a new
+feature called `abc`.  You can follow these steps to add the module,
+
+1. Install PySCF-forge in editable installation mode.
+
+2. Create a folder named `pyscf-forge/pyscf/abc`.  Due to the editable
+installation mode, this folder can be readily imported as a regular `pyscf`
+module.
+```
+>>> from pyscf import abc
+>>> print(abc)
+<module 'pyscf.abc' (namespace)>
+
+>>> print(abc.__path__)
+_NamespacePath(['path/to/pyscf-forge/pyscf/abc'])
+```
+
+3. Add Python code files to the `pyscf-forge/pyscf/abc` directory.  This
+process is similar to developing new methods for PySCF.  For example, you
+can add the following Python files into the `pyscf-forge/pyscf/abc` folder,
+```
+pyscf-forge
+├── ...
+└── pyscf
+    ├── ...
+    └── abc
+        ├── __init__.py
+        ├── rabc.py 
+        └── uabc.py
+```
+
+### Path Conflicts
+
+What if you want to add a feature to a module that already exists in PySCF?
+For example, if you want to add a new method, like `pp_rpa.py`, to the
+`pyscf/tdscf` folder, this could conflict with the existing `pyscf.tdscf`
+module in the PySCF core repository.  Adding features to existing modules
+requires more a slightly more complex configuration.
+
+To import the `pp_rpa` module from the PySCF-forge repository, you will need to
+modify the `__init__.py` file of the PySCF core module.  Add the following line
+of code to modify the `__path__` attribute of the `pyscf.tdscf` module,
+```python
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)
+```
+This command extends the search path of the `tdscf` module, resulting in the
+`__path__` attribute being set to
+```
+['/path/to/pyscf/pyscf/tdscf',
+ '/path/to/pyscf-forge/pyscf/tdscf']
+```
+This configuration allows Python to locate and load the new `pp_rpa.py` module
+from the extended directory in PySCF-forge.
+
+Note that the PySCF core `tdscf` folder already contains an `__init__.py` file.
+To avoid overwriting the existing `__init__.py` file in PySCF during the
+installation of PySCF-forge, you should not add an `__init__.py` file in the
+`pyscf-forge/pyscf/tdscf` directory.
+
+The structure of PySCF and PySCF-forge can be organized as follows,
+```
+pyscf
+├── ...
+└── pyscf
+    ├── ...
+    └── tdscf
+        ├── __init__.py  // modify the __path__ attribute in pyscf core module
+        ├── rhf.py
+        ├── rks.py
+        └── ...
+
+pyscf-forge
+├── ...
+└── pyscf
+    ├── ...
+    └── tdscf  // no __init__.py file in pyscf-forge
+        └── pp_rpa.py
+```
+
+When installing the PySCF-forge wheels using `pip install` in the normal
+installation mode, the `pp_rpa.py` file will be added to the `pyscf/tdscf`
+folder, integrating seamlessly as part of the regular PySCF module.  After this
+standard installation, there is no need to adjust the `__path__` attribute, as
+all features and modules are located within the same directory.