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. 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 section. For example,

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,

__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.