Metadata-Version: 2.4
Name: surfacia
Version: 3.0.2
Summary: A comprehensive Python package for molecular structure-activity relationship (QSAR/QSPR) studies with interactive SHAP visualization and AI-powered 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: 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 - Surface Atomic Chemical Interaction Analyzer

Version: 3.0.0

## Project Overview

Surfacia is a surface atomic chemical interaction analyzer based on quantum chemical calculations, designed for molecular property prediction and machine learning analysis. This tool integrates a complete workflow from SMILES strings to final property predictions.

## Key Features

- **SMILES Conversion**: Convert SMILES strings to 3D molecular structures
- **Geometry Optimization**: Fast geometry optimization using XTB
- **Quantum Chemical Calculations**: Generate and run Gaussian calculations
- **Property Analysis**: Molecular property analysis using Multiwfn
- **Feature Extraction**: Extract atomic-level and functional group-level molecular descriptors
- **Machine Learning**: Integrated machine learning analysis tools
- **Visualization**: Interactive SHAP analysis and molecular visualization

## Installation

### System Requirements
- Python >= 3.7
- Linux/Windows/macOS

### Installation Steps

```bash
# 1. Clone the repository
git clone https://github.com/yourusername/surfacia.git
cd surfacia

# 2. Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# or venv\Scripts\activate  # Windows

# 3. Install dependencies
pip install -r requirements.txt

# 4. Install surfacia package
pip install -e .  # Development mode

## Usage

### Command Line Interface

# View help
surfacia --help

# Complete workflow example:
surfacia smi2xyz -i molecules.csv
surfacia xtb-opt
surfacia xyz2gaussian
surfacia run-gaussian
surfacia multiwfn
surfacia extract-features -i FullOption2.csv -m 3
surfacia ml-analysis -i FinalFull.csv --test-samples 1,2,3
surfacia shap-viz -i Training_Set_Detailed.csv -x ./xyz_files/

Workflow Steps
SMILES to XYZ: Read SMILES from CSV file and generate 3D structures
Geometry Optimization: Optimize molecular geometry using XTB (optional)
Gaussian Calculations: Generate input files and run quantum chemical calculations
Multiwfn Analysis: Calculate molecular surface properties and descriptors
Feature Extraction: Extract atomic and functional group features
Machine Learning Analysis: Perform feature selection and model training
Result Visualization: Interactive analysis using SHAP

Input File Format
CSV files should contain the following columns:
smiles: SMILES strings
target: Target property values
Other experimental feature columns (optional)

## Required External Software
XTB Installation
Official Documentation: https://xtb-docs.readthedocs.io/en/latest/setup.html

Gaussian Installation
Detailed Installation Guide: http://sobereva.com/439

Multiwfn Installation
Official Website: http://sobereva.com/multiwfn/

Configuration
Environment Variables
Add these to your ~/.bashrc (Linux) 
## 许可证

MIT License

## 作者

Yuming Su (823808458@qq.com)
