Installation and versions

Use an isolated environment. Python 3.10–3.12 is a practical choice for the pinned ML stack; the declared minimum is 3.9. New Python releases may lack binary wheels. Linux is recommended for the full quantum workflow.

python -m venv .venv
# Linux / macOS
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install --upgrade "surfacia[viz]==4.0.0"
python -c "import surfacia; print(surfacia.__version__)"
surfacia --help

This manual covers 4.0.0. The upgrade removes the former candidate-ranking extension from 3.0.3. Verify the version printed above. If a package mirror still serves the older release, use the official index:

python -m pip install --upgrade --index-url https://pypi.org/simple "surfacia[viz]==4.0.0"

For development, install from GitHub source:

git clone https://github.com/sym823808458/Surfacia.git
cd Surfacia
python -m pip install -e ".[viz]"

ML constraints remain xgboost>=2.1.4,<3 and shap>=0.48,<0.49. The full quantum workflow additionally needs xTB, Gaussian (g16, formchk) and Multiwfn, separately installed and licensed. They are not in the pip wheel. The descriptor-table case needs none of them. Install viz for py3Dmol and interactive visualization. Next: Start from a descriptor table.