Skip to content

USAGE_GUIDE.md

Latest commit

 

History

History
300 lines (206 loc) · 5.67 KB

USAGE_GUIDE.md

File metadata and controls

300 lines (206 loc) · 5.67 KB

Spinach NMR - Python调用完整指南

✅ 安装状态

你的环境已经完全配置好！

  • ✅ MATLAB R2025b 已安装
  • ✅ 所有6个必需工具箱已安装
  • ✅ MATLAB Engine API for Python 已安装
  • ✅ conda matlab环境已配置

📁 项目文件说明

我为你创建了以下文件：

文件 用途
python_matlab_wrapper.py SpinachEngine封装类
spinach_demo.py 交互式示例程序 ⭐
run_spinach_example.py 自动化启动示例
test_matlab_connection.py 连接测试脚本
check_toolboxes.m 工具箱检查脚本
INSTALL_TOOLBOXES_GUIDE.md 工具箱安装指南

🚀 快速开始

方法1: 交互式演示（推荐）

# 激活conda环境
conda activate matlab

# 进入项目目录
cd /home/tony/Spinach-2.10.1

# 运行交互式演示
python spinach_demo.py

这会显示菜单让你选择不同的示例。

方法2: 基础启动

import matlab.engine

# 启动MATLAB引擎
eng = matlab.engine.start_matlab()

# 配置Spinach
eng.cd('/home/tony/Spinach-2.10.1')
eng.run_spinach('add', nargout=0)

# 现在可以调用任何Spinach函数！
eng.version()  # 获取MATLAB版本

# 完成后关闭
eng.quit()

方法3: 使用封装类

from python_matlab_wrapper import SpinachEngine

with SpinachEngine() as spinach:
    # 执行MATLAB命令
    result = spinach.execute_command("1 + 1")

    # 调用Spinach函数
    spin_system = spinach.call_spinach_function('bootstrap', 'hush')

    # 运行脚本
    spinach.run_simulation('examples/nmr_liquids/basic_2spin.m')

📚 Spinach示例目录

Spinach包含623个示例脚本，按类别组织：

推荐入门示例

基础知识 (examples/fundamentals/):

  • 基本自旋系统设置
  • 哈密顿量构建
  • 演化算子

液体NMR (examples/nmr_liquids/):

  • basic_2spin.m - 基本二自旋系统
  • cosy_demo.m - COSY谱仿真
  • hsqc_demo.m - HSQC谱

固体NMR (examples/nmr_solids/):

  • 魔角旋转(MAS)
  • 多量子谱

弛豫理论 (examples/relaxation_theory/):

  • T1/T2弛豫
  • NOE效应

💻 编程示例

示例1: 创建自旋系统

import matlab.engine

eng = matlab.engine.start_matlab()
eng.cd('/home/tony/Spinach-2.10.1')
eng.run_spinach('add', nargout=0)

# 创建系统参数
sys = eng.struct()
sys.magnet = 9.4  # 磁场强度
sys.isotopes = matlab.str(['1H', '13C'])  # 同位素

# 调用create函数
spin_system = eng.create(sys)

示例2: 运行预设脚本

# 运行液体NMR示例
eng.cd('/home/tony/Spinach-2.10.1/examples/nmr_liquids')
eng.run('basic_2spin.m')

示例3: NumPy数据交互

import numpy as np
from python_matlab_wrapper import AdvancedSpinachWrapper

wrapper = AdvancedSpinachWrapper()

# NumPy数组转MATLAB
data = np.array([[1, 2], [3, 4]])
matlab_data = wrapper.numpy_to_matlab(data)
wrapper.engine.set_variable('data', matlab_data)

# 在MATLAB中处理
wrapper.engine.execute_command("result = data * 2")

# 获取结果并转回NumPy
result = wrapper.engine.get_variable('result')
final_result = wrapper.matlab_to_numpy(result)

🔧 常用命令

MATLAB命令

% 查看Spinach版本
version

% 获取帮助
help create
help spin_system

% 列出当前工作区变量
whos

% 设置工作目录
cd('/home/tony/Spinach-2.10.1/examples/nmr_liquids')

% 运行脚本
run('basic_2spin.m')

Python命令

# 执行MATLAB命令
eng.eval('version')

# 调用函数
eng.function_name(arguments)

# 获取变量
var = eng.workspace['variable_name']

# 设置变量
eng.workspace['var_name'] = value

📖 学习资源

官方文档

推荐学习路径

  1. 第一步: 运行 spinach_demo.py 选择示例2，查看基础教程
  2. 第二步: 运行 examples/nmr_liquids/basic_2spin.m 理解基本流程
  3. 第三步: 阅读 examples/fundamentals/ 中的脚本
  4. 第四步: 修改示例参数，创建自己的仿真

🎯 实际应用示例

1D NMR谱仿真

eng.cd('/home/tony/Spinach-2.10.1/examples/nmr_liquids')

# 设置系统参数
eng.eval("sys.magnet=9.4;")
eng.eval("sys.isotopes={'1H'};")
eng.eval("sys.groups={{'spin1'}};")

# 创建并运行
eng.run('your_1d_simulation.m')

2D相关性谱

# COSY谱示例
eng.run('cosy_demo.m')

# HSQC谱示例
eng.run('hsqc_demo.m')

⚠️ 注意事项

  1. 并行池: Spinach会自动启动31个工作进程，这是正常的
  2. 内存: 大规模仿真可能需要大量内存
  3. 时间: 复杂仿真可能需要较长时间
  4. 路径: 确保每次都先运行 run_spinach('add')

🆘 故障排除

问题1: MATLAB Engine未找到

# 重新安装
cd /home/tony/matlab/extern/engines/python
/home/tony/anaconda3/envs/matlab/bin/python -m pip install .

问题2: Spinach函数未找到

# 确保Spinach路径已添加
eng.cd('/home/tony/Spinach-2.10.1')
eng.run_spinach('add', nargout=0)

问题3: 并行池问题

# 检查并行池状态
eng.eval('gcp('nocreate')')

# 删除现有池
eng.eval('delete(gcp('nocreate'))')

📝 快速参考卡

启动: conda activate matlab
进入: cd /home/tony/Spinach-2.10.1
演示: python spinach_demo.py
测试: python test_matlab_connection.py

🎉 开始使用

现在你可以：

  1. ✅ 运行 python spinach_demo.py 开始探索
  2. ✅ 查看 examples/ 目录中的623个示例
  3. ✅ 访问 https://spindynamics.org/wiki/ 获取详细文档
  4. ✅ 修改示例创建你自己的NMR仿真

祝你使用愉快！ 🧪✨