SpinachPython 🧪

🎯 通过Python完整控制Spinach NMR仿真，查看所有输入输出

✨ 特性

• 🔍 完整的输入输出显示 - 查看所有NMR仿真参数、过程和结果
• 📊 自动可视化 - 一键生成NMR谱图
• 💻 交互式Shell - 方便的命令行界面
• 📚 623个示例 - 涵盖所有NMR领域
• 🐍 Python封装 - 优雅的Python API
• 📝 详细文档 - 完整的使用指南

🚀 快速开始

前提条件

• ✅ MATLAB R2024a+ (含6个工具箱)
• ✅ Python 3.11+
• ✅ Spinach 2.10.1+

安装

# 1. 克隆仓库
git clone https://github.com/your-username/spinachpython.git
cd spinachpython

# 2. 安装MATLAB Engine API
cd /path/to/matlab/extern/engines/python
python -m pip install .

# 3. 安装Python依赖
pip install -r requirements.txt

使用

# 运行交互式Shell（推荐）
python scripts/run_spinach_with_io.py

交互式命令：

Spinach>> list                    # 列出所有示例
Spinach>> run fundamentals        # 运行基础教程
Spinach>> workspace               # 查看工作区
Spinach>> get sys                 # 查看变量详情
Spinach>> plot spectrum          # 绘制谱图
Spinach>> eval 1+1                # 执行MATLAB代码
Spinach>> help                    # 帮助
Spinach>> quit                    # 退出

📖 文档

• 完整使用指南
• 输入输出功能
• 工具箱安装
• 功能总结

💻 代码示例

基础使用

from scripts.python_matlab_wrapper import SpinachEngine

# 使用封装类
with SpinachEngine() as spinach:
    # 执行命令
    result = spinach.execute_command("1 + 1")

    # 创建自旋系统
    spinach.create_spin_system(
        magnet=9.4,
        isotopes=['1H', '13C']
    )

    # 运行示例
    spinach.run_simulation('examples/nmr_liquids/basic_2spin.m')

高级使用

from scripts.run_spinach_with_io import SpinachRunner

runner = SpinachRunner()
runner.start()

# 运行示例
runner.run_example('nmr_liquids')

# 获取并可视化结果
data = runner.get_variable('spectrum')
if data is not None:
    runner.plot_data(data, 'My_Spectrum')

# 交互模式
runner.interactive_shell()
runner.cleanup()

📁 项目结构

spinachpython/
├── README.md                 # 主文档
├── requirements.txt          # Python依赖
├── .gitignore               # Git忽略文件
├── scripts/                 # Python脚本
│   ├── run_spinach_with_io.py      # 交互式Shell（推荐）
│   ├── spinach_demo.py             # 示例程序
│   ├── python_matlab_wrapper.py    # 封装类
│   ├── test_matlab_connection.py   # 测试脚本
│   └── ...
├── docs/                    # 文档
│   ├── USAGE_GUIDE.md
│   ├── IO_FEATURES_GUIDE.md
│   └── ...
└── examples/                # Spinach示例（需要Spinach安装）

🎯 主要功能

1️⃣ 完整的输入输出显示

• 输入参数 - 系统配置、哈密顿量、基组
• 执行过程 - 代码、时间、状态
• 输出结果 - 变量、统计、预览
• 自动绘图 - NMR谱图（PNG格式）

2️⃣ 623个Spinach示例

涵盖36个类别：

• fundamentals (基础教程) - 67个脚本
• nmr_liquids (液体NMR) - 65个脚本
• nmr_solids (固体NMR) - 65个脚本
• relaxation_theory (弛豫理论) - 38个脚本
• 还有32个其他类别...

3️⃣ 交互式Shell

Spinach>> list                    # 列出所有36个示例类别
Spinach>> run nmr_liquids         # 运行液体NMR示例
Spinach>> workspace               # 查看所有变量
Spinach>> get spin_system        # 查看变量详情
Spinach>> plot spectrum          # 绘制NMR谱图

🔧 需要的MATLAB工具箱

工具箱	用途
Parallel Computing Toolbox	并行计算加速
Deep Learning Toolbox	深度学习网络
Reinforcement Learning Toolbox	强化学习算法
Optimization Toolbox	优化算法
Statistics and Machine Learning Toolbox	统计分析
Mapping Toolbox	地图绘制

运行检查：

matlab -batch "run('docs/check_toolboxes.m')"

📊 输出示例

输入参数

▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶
  输入参数
▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶▶

系统配置:
----------------------------------------------------------------------
  magnet                    = 9.4
  isotopes                  = [1H, 13C]
  frames                    = [lab]
----------------------------------------------------------------------

结果显示

变量信息:
  类型: double
  形状: (1024,)
  数值范围: [-0.000234, 1.000000]

✓ 谱图已保存: spectrum_1234567890.png

🧪 测试

# 测试连接
python scripts/test_matlab_connection.py

# 快速测试
python scripts/quick_test.py

# 运行示例
python scripts/spinach_demo.py

📚 学习路径

初学者

Spinach>> run fundamentals
Spinach>> workspace
Spinach>> get sys

中级用户

Spinach>> run nmr_liquids
Spinach>> plot output
Spinach>> eval custom_code

高级用户

# 编写自定义脚本
from scripts.run_spinach_with_io import SpinachRunner

# 批量处理示例
for category in ['nmr_liquids', 'nmr_solids', 'relaxation_theory']:
    runner.run_example(category)

🆘 故障排除

MATLAB Engine未安装

cd /path/to/matlab/extern/engines/python
python -m pip install .

工具箱缺失

matlab -batch "run('docs/check_toolboxes.m')"

参考：工具箱安装指南

🤝 贡献

欢迎提交Issue和Pull Request！

📄 许可证

本项目采用MIT许可证 - 详见 LICENSE.md

Spinach软件遵循其原始许可证。

🙏 致谢

• Spinach - 快速NMR模拟库
• MATLAB Engine API - Python接口

📞 联系

如有问题，请提交Issue或查看文档。

---

开始使用 🚀：

conda activate matlab
python scripts/run_spinach_with_io.py

享受完整的NMR仿真体验！ 🧪✨