Metadata-Version: 2.4
Name: surfacia
Version: 4.0.0
Summary: Molecular surface descriptors, predictive modeling and chemically interpretable SHAP analysis
Author-email: YumingSu <823808458@qq.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/sym823808458/Surfacia
Project-URL: Bug Reports, https://github.com/sym823808458/Surfacia/issues
Project-URL: Source, https://github.com/sym823808458/Surfacia
Project-URL: Documentation, https://surfacia.readthedocs.io/
Keywords: chemistry,quantum-chemistry,molecular-descriptors,QSAR,QSPR,computational-chemistry,rdkit,gaussian,multiwfn,machine-learning,SHAP,molecular-visualization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: openbabel-wheel>=3.1.1
Requires-Dist: rdkit>=2022.9
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: xgboost<3.0.0,>=2.1.4
Requires-Dist: shap<0.49.0,>=0.48.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: zhipuai>=2.0.0
Requires-Dist: dash>=2.0.0
Requires-Dist: cclib>=1.7.2
Requires-Dist: click>=8.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: toml>=0.10.2
Requires-Dist: tqdm>=4.64.0
Requires-Dist: pathlib2>=2.3.7
Requires-Dist: joblib>=1.1.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: sphinx>=4.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "dev"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5.0; extra == "viz"
Requires-Dist: seaborn>=0.11.0; extra == "viz"
Requires-Dist: plotly>=5.0.0; extra == "viz"
Requires-Dist: py3Dmol>=2.0.0; extra == "viz"
Requires-Dist: ipywidgets>=7.6.0; extra == "viz"
Requires-Dist: ipython>=7.0.0; extra == "viz"
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0.0; extra == "notebook"
Requires-Dist: notebook>=6.4.0; extra == "notebook"
Requires-Dist: ipywidgets>=7.6.0; extra == "notebook"
Requires-Dist: ipython>=7.0.0; extra == "notebook"
Dynamic: license-file

# Surfacia

Molecular surface descriptors, predictive modeling and chemical interpretation.

Surfacia connects **SMILES → 3D → xTB/Gaussian → Multiwfn → descriptors → ML/SHAP**.
Choose whole-molecule, molecular-surface or local regions to relate a model's
predictions to chemical structure. It analyzes molecular surfaces; it does not
by itself simulate an electrode or a solid catalyst interface.

## Start with your data

- **Already have descriptors:** run the [downloadable 36-molecule tutorial](https://surfacia.readthedocs.io/zh-cn/latest/examples/descriptor_table.html).
- **Start from molecular structures:** follow the [surface workflow](https://surfacia.readthedocs.io/zh-cn/latest/user_guide/workflows.html).
- **Inspect model explanations:** open original predictions and ordinary SHAP in the [interactive case](https://surfacia.readthedocs.io/zh-cn/latest/examples/interpretation.html).
- **中文手册:** [切换到完整中文内容](https://surfacia.readthedocs.io/zh-cn/latest/zh/index.html).

## Install and check your version

```bash
python -m pip install --upgrade "surfacia[viz]"
python -c "import surfacia; print(surfacia.__version__)"
surfacia --help
```

The current version is **4.0.0**. Upgrade an existing 3.0.3 installation to remove
the former candidate-ranking extension. Check the printed version after installing.
For development from GitHub source:

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

Use a separate environment, preferably Python 3.10–3.12. The package declares
Python >=3.9. The ML compatibility ranges remain `xgboost>=2.1.4,<3` and
`shap>=0.48,<0.49`. The full quantum workflow additionally needs independently
installed/licensed xTB, Gaussian (`g16`, `formchk`) and Multiwfn. The descriptor-table
tutorial does not need these external tools.

## A runnable example

From the repository, after installing dependencies:

```bash
python examples/descriptor_table/make_data.py
surfacia ml-analysis -i examples/descriptor_table/descriptors.csv --manual --manual-features Full --test-samples "6,12,18,24,30,36" --epoch 32 --cores 1 --train-test-split 0.85 --no-generate-fitting
```

The six features and target are computed with RDKit. This is a reproducible
software tutorial, **not a quantum-surface benchmark or experimental logP validation**.
The current CLI uses XGBoost regression and repeated random splits. The manual
documents its evaluation boundaries and distinguishes it from a frozen research
benchmark. Ordinary SHAP is retained; attribution alone does not prove causality.

## Upgrade from 3.0.3

The former Go Beyond/SPES candidate-ranking extension is removed from current
source: no automatic ranking CSVs, ranking dashboard layer, `--spes-csv` option,
or `surfacia.ml.spes` API. Original regression predictions and SHAP interpretation
remain. See [migration notes](https://surfacia.readthedocs.io/zh-cn/latest/migration.html).
The major version marks removed interfaces, not a new quantum method. Historical
releases and manuscript archives remain available through their original records.

## Maintain and cite

- [Maintenance](https://github.com/sym823808458/Surfacia/blob/main/MAINTENANCE.md): update docs/cases and build/release checks.
- [Release audit](https://github.com/sym823808458/Surfacia/blob/main/RELEASE_AUDIT_20261019.md): GitHub, PyPI and Read the Docs findings.
- [Issues](https://github.com/sym823808458/Surfacia/issues)
- Author: Yuming Su / 苏禹铭 · 823808458@qq.com
- License: MIT. Cite the exact software version and commit; no publication DOI is assigned here.
