Metadata-Version: 2.2
Name: sisq
Version: 0.2.0
Summary: A Python Parser for the SISQ Quantum Instruction Set
Home-page: https://gitee.com/hpcl_quanta/quiet-parser.git
Author: Yuzhen Zheng, Zhengdong Tang, Xiang Fu
Author-email: gtaifu@gmail.com
Project-URL: Bug Tracker, https://gitee.com/hpcl_quanta/quiet-parser/issues
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: antlr4-python3-runtime==4.13.0
Requires-Dist: numpy

# SISQ Parser - Python Package

[![PyPI version](https://badge.fury.io/py/sisq.svg)](https://badge.fury.io/py/sisq)
[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

**SISQ (Simplified Instruction Set for Quantum computing)** 解析器的 Python 实现。SISQ 是一种专为量子计算设计的中间表示语言，支持量子门操作、脉冲控制、时序管理等功能。

## 🚀 特性

- **完整的量子指令集支持**：支持量子门、脉冲、时序、控制流等指令
- **模块化设计**：支持 cm(控制模块)、fm(浮点模块)、gm(量子门模块)、im(整数模块)、pm(脉冲模块)、tm(时序模块)
- **类型检查**：完善的变量类型检查和错误报告
- **布局管理**：支持量子比特和端口的物理布局定义
- **可扩展性**：基于 ANTLR 语法，易于扩展和修改
- **模拟器验证**：与 QuaLeSim 模拟器无缝集成
- **灵活的输入输出**：支持文件、标准输入、字符串等多种输入方式

## 📦 安装

### 从 PyPI 安装（推荐）

```bash
pip install sisq
```

### 从源码安装

```bash
git clone https://gitee.com/hpcl_quanta/sisq-parser.git
cd sisq-parser/python
pip install -e .
```

## 📖 快速开始

### 基本使用

```python
from sisq import SisqParser

# 创建解析器实例
parser = SisqParser()

# 解析 SISQ 文件
prog = parser.parse("path/to/file.sisq")

# 检查解析错误
errors = parser.get_all_errors()
if errors:
    for error in errors:
        print(error)
else:
    print("解析成功！")
    # 访问解析后的程序结构
    print(f"程序包含 {len(prog.sections)} 个节")
```

### 从字符串解析

```python
from sisq import SisqParser

parser = SisqParser()
sisq_code = """
using im, gm
.code:
    def_func test(qubit q):
        H q
    end
.entry:
    qubit q
    test(q)
"""

prog = parser.parse(sisq_code, is_string_content=True)
```

### 打印抽象语法树

```python
from sisq import SisqParser

parser = SisqParser()
prog = parser.parse("file.sisq", cst_print=True)  # 打印 CST
```

## 📚 API 文档

### SisqParser

主要的解析器类，用于解析 SISQ 文件。

#### 方法

- **`parse(input_source, cst_print=False, is_string_content=False)`**
  
  解析 SISQ 输入并返回程序对象。
  
  **参数：**
  - `input_source` (str): 文件路径或字符串内容
  - `cst_print` (bool): 是否打印具体语法树（CST），默认 False
  - `is_string_content` (bool): 如果为 True，将 `input_source` 视为字符串内容而非文件路径，默认 False
  
  **返回：**
  - `SISQProgram`: 解析后的程序对象

- **`get_all_errors()`**
  
  获取解析过程中收集的所有错误信息。
  
  **返回：**
  - `list`: 错误信息列表

- **`print_all_errors()`**
  
  打印所有解析错误。

### SISQProgram

解析后的程序对象，包含程序的各个节（sections）。

#### 属性

- `sections`: 程序的所有节（FileSection 对象列表）
- `modules`: 使用的模块列表
- `code_section`: 代码节
- `entry_section`: 入口节
- `layout_section`: 布局节

### SisqVisitor

访问器类，用于遍历和访问解析树。

## 💡 使用示例

### 示例 1：解析并检查程序结构

```python
from sisq import SisqParser

parser = SisqParser()
prog = parser.parse("qft.sisq")

# 检查是否有错误
if parser.get_all_errors():
    parser.print_all_errors()
else:
    # 访问程序结构
    print(f"使用的模块: {prog.modules}")
    print(f"代码节中的函数数量: {len(prog.code_section.functions)}")
    print(f"入口节中的语句数量: {len(prog.entry_section.statements)}")
```

### 示例 2：处理解析错误

```python
from sisq import SisqParser

parser = SisqParser()
try:
    prog = parser.parse("invalid.sisq")
except Exception as e:
    print(f"解析失败: {e}")

# 获取详细错误信息
errors = parser.get_all_errors()
for error in errors:
    print(f"错误: {error}")
```

## 📋 依赖

- Python 3.7+
- `antlr4-python3-runtime==4.13.0`
- `numpy`

## 🔗 相关资源

- **项目仓库**：[GitHub Repository](https://gitee.com/hpcl_quanta/sisq-parser)
- **问题报告**：[GitHub Issues](https://gitee.com/hpcl_quanta/sisq-parser/issues)
- **完整文档**：查看项目根目录的 [README.md](../README.md) 了解更多信息

## 📄 许可证

本项目采用 Apache 2.0 许可证。

## 🙏 致谢

- 感谢 [ANTLR](https://www.antlr.org/) 提供强大的语法解析工具
- 感谢所有贡献者的努力和支持

---

<div align="center">
  <sub>Built with ❤️ for the quantum computing community</sub>
</div>

