Skip to content

Latest commit

 

History

History
427 lines (280 loc) · 19.7 KB

CONTRIBUTING_CN.md

File metadata and controls

427 lines (280 loc) · 19.7 KB

MindSpore Quantum贡献指南

View English

贡献者许可协议

向MindSpore Quantum社区提交代码之前,您需要阅读并签署《贡献者许可协议(CLA)》。

个人贡献者请参见ICLA在线文件

量子计算简介

随着摩尔定律的逐渐失效,集成电路板制程提升和芯片性能提升愈加困难,算力到达瓶颈期。经典计算机的架构已近极限,在大模型算力要求越加突出的当下,量子计算这种新型的技术领域逐渐得到大众的关注。

量子是个物理学的概念,意思是最小化、不可再分的基本单位,最小单位即是量子;不可再分的概念称之为量子化。可以用于描述微观物理世界中的粒子特性,例如原子,电子。“量子”来自于拉丁语quantum,意译是“一定数量的物质”。

量子计算是一项前沿技术,使用量子力学的规律调控量子信息单元进行计算。简言之,操纵量子比特用于计算机。当前,人们使用手机、电脑、其他媒介刷到本文章,其软件底层都是0和1数据流,对应的硬件控制就是高低电平;而量子计算操控的是量子比特,具备量子态特性的微观粒子。

量子计算的应用相当广泛,在密码解析、交通运输问题(组合优化数学问题),材料化工、生物医学(化学分子能量模拟计算),人工智能(量子-机器学习),新型半导体(量子芯片)等领域有着广泛应用。 $$ 量子态\|\varphi>=\alpha |0>+\beta |1> $$

安装与开发

安装

安装MindSpore

请根据MindSpore官网安装指南,安装1.4.0及以上版本的MindSpore。

MindSpore是一种适用于端边云场景的新型开源深度学习训练/推理框架。 MindSpore提供了友好的设计和高效的执行,旨在提升数据科学家和算法工程师的开发体验。

pip安装

  • 安装MindQuantum
pip install mindquantum

源码安装

  1. 从代码仓下载源码

    cd ~
    git clone https://gitee.com/mindspore/mindquantum.git
  2. 编译MindQuantum

    Linux系统下请确保安装好CMake >= 3.18.3,然后运行如下命令:

    cd ~/mindquantum
    bash build.sh --gitee

    这里 --gitee 让脚本从gitee代码托管平台下载第三方依赖。如果需要编译GPU版本,请先安装好 CUDA 11.x,和对应的显卡驱动,然后使用--gpu参数,执行如下编译指令:

    cd ~/mindquantum
    bash build.sh --gitee --gpu

    Windows系统下请确保安装好MinGW-W64和CMake >= 3.18.3,然后运行如下命令:

    cd ~/mindquantum
    build.bat /Gitee

    Mac系统下请确保安装好openmp和CMake >= 3.18.3,然后运行如下命令:

    cd ~/mindquantum
    bash build.sh --gitee
  3. 安装编译好的whl包

    进入output目录,通过pip命令安装编译好的mindquantum的whl包。

验证是否成功安装

执行如下命令,如果没有报错No module named 'mindquantum',则说明安装成功。

python -c 'import mindquantum'

编译

MindQuantum提供编译出包本地编译两种方法

1.编译出包,如果用户需要适配不同的系统环境、python版本,则可以将源码编译成wheel包,再安装,详细流程可参考上文[源码安装](# 源码安装)。

2.本地编译,如果用户新增或修改部分代码,需要快速验证是否生效,则可以使用本地编译,将C++代码编译成*.so文件,再使用Python调用,并设置环境变量,不需要重新编译出包,再卸载并重新安装,方便调试验证。

从代码仓下载源码

cd ~
git clone https://gitee.com/mindspore/mindquantum.git
  • Linux系统,依赖于CMake >= 3.18.3,本地编译。

    --gitee参数是指定脚本从gitee代码托管平台下载第三方依赖;export命令是添加mindquantum源码路径到PYTHONPATH环境变量里。

    cd ~/mindquantum
    
    bash build_locally.sh --gitee
    export PYTHONPATH=`pwd`$PYTHONPATH
  • Windows系统,依赖于MinGW-W64和CMake >= 3.18.3,本地编译。

    cd ~/mindquantum
    build_locally.bat /Gitee -G 'MinGW Makefiles'
    set PYTHONPATH=%cd%;%PYTHONPATH%
  • Mac系统,依赖于openmp和CMake >= 3.18.3,本地编译。

    cd ~/mindquantum
    bash build_locally.sh --gitee
    export PYTHONPATH=`pwd`$PYTHONPATH
  • 系统依赖组件安装

    • GCC-GNU编译器套件,安装说明

      1.Linux和MacOS安装

      1.1Linux/Ubuntu/Centos系统和MacOS系统会自带gcc,版本满足编译MindQuantum。

      1.2使用命令安装gcc

      # Ubuntu 安装
      apt-get update
      apt-get install gcc
      apt-get install build-essential
      
      # Centos 安装
      yum install gcc gcc-c++
      
      # 输出gcc版本,验证安装成功
      gcc --version

      2.Window安装

      2.1 Window的C/C++编译器套件通常推荐Mingw-w64,可用于编译和运行Window应用和DLL文件。

      2.2 进入Mingw-w64安装包页面,下载离线安装包。这里推荐x86_64-posix-seh版本,对应x64架构。

      2.3 本地双击打开安装包,按照提示,进行安装。(需要注意,写入环境变量)

      2.4安装完毕,打开cmd终端,输入命令

      C:\Users\xx>gcc --version
      
      gcc (x86_64-win32-seh-rev0, Built by MinGW-W64 project) 8.1.0
      Copyright (C) 2018 Free Software Foundation, Inc.

      遇到bug,可发issue,或谷歌百度,参考csnd教程

    • CMake-跨平台的开源构建程序,安装说明

      1.进入CMake官网,根据系统选择合适的版本的安装包。

      Windows系统推荐cmake-3.2*-windows-x86_64.msi

      Macos系统推荐cmake-3.2*-macos-universal.dmg

      Linux系统推荐cmake-3.2*-linux-x86_64.sh

      2.本地双击打开CMake安装包,依照提示安装,注意需要将CMake添加进用户变量中,最后点击Finish,安装完毕。

      3.打开终端,在命令行中输出命令,输出版本号即表示成功。

      cmake --version
      >>> cmake version 3.24.2

开发

mindquantum主要使用C++和python进行开发,核心计算单元使用C/C++实现,上层接口及周边模块使用Python实现

开发流程主要分成2类,开发新功能,修复缺陷bug:

  • 开发新功能,进入MindQuantum的issue页面,提交issue,编写新功能描述、类别、实现方法等。与MindQuantum开发团队交流,确认该功能是否必要。本地着手实现,编写代码,实现功能,编写相应的测试用例,相应的说明文档。提交PR,待代码通过审查后合入主分支,新功能开发完毕。

  • 修复缺陷bug,进入MindQuantum的issue页面,阅读未关闭的issue,认领issue解决问题。或者平时使用MindQuantum遇到bug,欢迎提交issue,帮助完善MindQuantum功能模块。

快速入门

  • Gitee上fork mindquantum代码仓。
  • 参见README_CN.md了解项目信息和构建说明。
  • 初体验-搭建参数化量子线路 使用 mindquantum搭建包括H门、RX门和RY门的量子线路,并得到量子态
from mindquantum import *
import numpy as np

encoder = Circuit().h(0).rx({'a0': 2}, 0).ry('a1', 1)
print(encoder)
print(encoder.get_qs(pr={'a0': np.pi / 2, 'a1': np.pi / 2}, ket=True))

运行上述代码,将会输出量子线路和末态

      ┏━━━┓ ┏━━━━━━━━━━┓
q0: ──┨ H ┠─┨ RX(2*a0) ┠───
      ┗━━━┛ ┗━━━━━━━━━━┛
      ┏━━━━━━━━┓
q1: ──┨ RY(a1) ┠───────────
      ┗━━━━━━━━┛
-1/2j¦00⟩
-1/2j¦01⟩
-1/2j¦10⟩
-1/2j¦11⟩

代码结构

单元测试

mindquantum基于pytest编写单元测试用例,建议开发者在实现一个新的功能、模块后,编写对应的单元测试用例,保证功能正常

编写文档

编写文档的说明指南,MindQuantum 有两种主要类型的文档:

  • 面向用户的文档:这些是用户在MindSpore Quantum网站上看到的文档,包括线路构建,模拟器,算法实现等教程教案,有助于快速入手并应用MindQuantum,也有利于学习量子计算算法。
  • 面向开发人员的文档:面向开发人员的文档分布在代码库MindQuanntum/docs中。如果有兴趣添加新的开发人员文档,请阅读wiki 上的此页面,了解最佳实践,并在编写代码后及时书写注释,API是通过抽取代码中的注释信息整理而成。

贡献流程

代码风格

请遵循此风格,以便MindSpore Quantum团队审查、维护和开发。

  • 编码指南

    MindSpore Quantum社区使用Python PEP 8 编码风格谷歌C++编码风格。建议在IDE中安装以下插件,用于检查代码格式:CppLintCppCheckCMakeLintCodeSpellLizardShellCheckPyLint

  • 单元测试指南

    MindSpore社区使用Python单元测试框架pytest。注释名称需反映测试用例的设计意图。

  • 重构指南

    我们鼓励开发人员重构我们的代码,以消除代码坏味道。所有代码都要符合编码风格和测试风格,重构代码也不例外。无注释的代码行(nloc)的Lizard阈值为100,圈复杂度(cnc)的阈值为20。当收到Lizard警告时,必须重构要合并的代码。

  • 文档指南

    我们使用MarkdownLint来检查Markdown文档格式。MindSpore CI基于默认配置修改了以下规则。

    • MD007(无序列表缩进):参数indent设置为4,表示无序列表中的所有内容都需要缩进4个空格。
    • MD009(行尾空格):参数br_spaces设置为2,表示行尾可以有0或2个空格。
    • MD029(有序列表的序列号):参数style设置为ordered,表示升序。

    有关详细信息,请参见规则

Fork-Pull开发模型

  • Fork MindSpore代码仓

    在提交代码至MindSpore项目之前,请确保已fork此项目到您自己的代码仓。MindSpore代码仓和您自己的代码仓之间可能会并行开发,请注意它们之间的一致性。

  • 克隆远程代码仓

    如果您想将代码下载到本地计算机,最好使用Git方法:

    # 在Gitee上
    
    git clone https://gitee.com/{insert_your_forked_repo}/mindquantum.git
  • 本地开发代码。

为避免分支不一致,建议切换到新分支:

git checkout -b {新分支名称} origin/master

以master分支为例,如果MindSpore Quantum需要创建版本分支和下游开发分支,请先修复上游的bug,

再更改代码。

  • 将代码推送到远程代码仓。

    更新代码后,以正式的方式推送更新:

git add .
git status # 查看更新状态。
git commit -m "你的commit标题"
git commit -s --amend # 添加commit的具体描述,可选。
git push origin {新分支名称}
  • 新建Pr提交到MindSpore Quantum代码仓。

在最后一步中,您需要在新分支和MindSpore Quantum主分支之间拉取比较请求。完成拉取请求后,Jenkins CI将自动设置,进行构建测试。拉取请求应该尽快合并到上游master分支中,以降低合并的风险。

最后一步,您需要在您的代码仓点击Pull Requests,新建Pr,选择源分支和目标分支,比较更新后的代码差异。提交Pr请求后,评论区会出现i-robot小助手进行操作说明。

如果您是第一次提交Pr,将会出现mindspore-cla/no标签,i-robot小助手会提示您签署贡献者许可协议。如果已经签署过,则会出现mindspore-cla/yes标签。

然后,在评论区输入/retest,触发Jenkins CI门禁系统,进行编译构建、代码语法、单元测试等相关测试,保证合入的代码质量。

报告Issue

发现问题后,建议以报告issue的方式为项目作出贡献。错误报告应尽量书写规范,内容详尽,感谢您对项目作出的贡献。

报告issue时,请参考以下格式:

  • 说明您使用的环境版本(MindSpore、OS、Python等)。

  • 说明是错误报告还是功能需求。

  • 说明issue类型,添加标签可以在issue板上突出显示该issue。

  • 问题是什么?

  • 期望如何处理?

  • 如何复现?(尽可能精确具体地描述)

  • 给审核员的特别说明。

Issue咨询:

  • 解决issue时,请先评论,告知他人由您来负责解决该issue。

  • 对于长时间未关闭的issue,建议贡献者在解决该issue之前进行预先检查。

  • 如您自行解决了自己报告的issue,仍需在关闭该issue之前告知他人。

  • 如需issue快速响应,可为issue添加标签。标签详情,参见标签列表

提交PR

  • Gitee上通过issue提出您的想法。

  • 如果是需要大量设计细节的新功能,还应提交设计方案。

  • 经issue讨论和设计方案评审达成共识后,在已fork的代码仓开发,并提交PR。

  • 任何PR至少需要位2位审批人的LGTM标签。请注意,审批人不允许在自己的PR上添加LGTM标签。

  • 经充分讨论后,根据讨论的结果合并、放弃或拒绝PR。

PR咨询:

  • 避免不相关的更改。

  • 确保您的commit历史记录有序。

  • 确保您的分支与主分支始终一致。

  • 用于修复错误的PR中,确保已关联所有相关问题。

本地代码自检

在开发过程中,建议使用pre-push功能进行本地代码自检,可以在本地进行类似CI门禁上Code Check阶段的代码扫描,提高上库时跑门禁的成功率。使用方法请参见pre-push快速指引

开发完成后,建议vscodepycharm的格式化功能,规范代码风格。