Surfacia
SURF Atomic Chemical Interaction Analyzer,Surfacia,表面原子化学相互作用分析程序
Ask AI about Surfacia
Powered by Claude · Grounded in docs
I know everything about Surfacia. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Surfacia
Surface Atomic Chemical Interaction Analyzer for descriptor extraction and interpretable machine learning in computational chemistry.
At a Glance
- End-to-end workflow:
SMILES -> 3D -> xTB/Gaussian -> Multiwfn -> descriptors -> ML/SHAP - CLI-first design for local and remote Linux/HPC usage
- Supports full workflow mode and modular step-by-step execution
Current Release
- Latest stable version: 3.0.2
- Python requirement: >= 3.9
- License: MIT
PyPI: https://pypi.org/project/surfacia/
Quick Install (Recommended for Most Users)
# optional but recommended
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install surfacia
Check installation:
surfacia --help
python -c "import surfacia; print(surfacia.__version__)"
Important Compatibility Note (ML Stage)
To avoid ML parsing failures such as:
could not convert string to float: '[-3.xxxE0]'
use the validated dependency range:
xgboost>=2.1.4,<3.0.0shap>=0.48.0,<0.49.0
Quick fix:
pip install --force-reinstall "xgboost==2.1.4" "shap==0.48.0"
External Software Requirements
Surfacia orchestrates external quantum-chemistry tools. Ensure these commands are available in your PATH:
xtbg16(andformchk)MultiwfnorMultiwfn_noGUI
Minimal Usage
Run full workflow:
surfacia workflow -i molecules.csv --test-samples "1,3"
Run ML only (for existing descriptor table):
surfacia ml-analysis -i FinalFull_Mode3_20_168.csv \
--max-features 1 --stepreg-runs 1 \
--train-test-split 0.85 --epoch 32 --cores 8 \
--test-samples "1,2,3"
MCP Server (New)
Surfacia now ships an MCP stdio server so agent clients can call workflow stages as structured tools.
Start MCP server:
surfacia-mcp --log-level INFO
# or
python -m surfacia.mcp.server --log-level INFO
Typical first tool calls:
surfacia_check_environmentsurfacia_detect_workflow_state
Source Install (Developers)
git clone https://github.com/sym823808458/Surfacia.git
cd Surfacia
pip install -e .
Documentation
- Full docs: https://surfacia.readthedocs.io/
- Troubleshooting: https://surfacia.readthedocs.io/en/latest/user_guide/troubleshooting.html
- Mode3 top-20 remote debug example: https://surfacia.readthedocs.io/en/latest/examples/mode3_top20_remote_debug.html
- MCP server guide: https://surfacia.readthedocs.io/en/latest/integrations/mcp_server.html
Citation
If Surfacia helps your research, please cite the project and related publication when available.
Contact
- Author: Yuming Su
- Email: 823808458@qq.com
- Academic homepage: https://sym823808458.github.io/yumingsu_homepage/
- Issues: https://github.com/sym823808458/Surfacia/issues
