科学计算【免费下载链接】CirqPython framework for creating, editing, and running Noisy Intermediate-Scale Quantum (NISQ) circuits.项目地址https://gitcode.com/gh_mirrors/ci/Cirq点击查看免费下载本文是一份面向 Cirq 贡献者的完整开发操作手册覆盖了 docs/dev/development.md 所总结的开发者日常任务克隆与 Fork 仓库、配置 git、用 apt 与 virtualenvwrapper 搭建开发环境、按模块做 editable 安装、重建 Protocol Buffers、运行本地测试与持续集成检查、编写规范 docstring 以及管理生产/开发依赖。读完本文你将能够在自己的机器上从零建立一套可编辑、可测试、可提交的 Cirq 开发工作区并理解每个 check 脚本背后依赖的源码机制。文中所有命令默认面向 Debian 环境且除首次克隆外均假设当前工作目录为本地 Cirq 仓库根目录。1. 获取源码克隆仓库与推荐的 git 配置1.1 克隆仓库获取一份可编辑的本地 Cirq 副本最简单的方式是克隆仓库git clone https://gitcode.com/gh_mirrors/ci/Cirq.git cd Cirq克隆完成后仓库根目录下即包含多个独立发布的模块目录cirq-core、cirq-google、cirq-ionq、cirq-aqt、cirq-pasqal、cirq-web以及用于开发的dev_tools/与存放全部检查脚本的check/目录。1.2 推荐 git 配置忽略大规模重构提交Cirq 历史上做过多次全库范围的格式化重构这些提交会污染git blame的溯源结果。仓库为此维护了一份.git-blame-ignore-revs文件根目录下其中逐行记录了迁移到 black 格式化器为字符串应用 flynt 格式化按新版 black 规则重排等大规模改动的 commit hash。执行下面的命令即可让git blame自动忽略这些提交git config blame.ignoreRevsFile .git-blame-ignore-revs提示如果你使用 PyCharm修改后可能需要执行Restart Invalidate Caches才能让该配置生效。1.3 Fork 工作流为提交 PR 准备远程仓库如果计划向 Cirq 主仓库提交代码推荐标准的 Fork 工作流在代码托管平台上 Fork Cirq 仓库点击仓库页面右上角的 Fork 按钮Fork 会在你的账号下创建一个独立的仓库副本。克隆你 Fork 出来的仓库到本地并进入该目录git clone 你的 fork 仓库地址 cd Cirq也可以直接使用仓库页面 Clone or Download 绿色按钮提供的地址。添加名为upstream的远程指向 Cirq 主仓库区别于刚克隆的origin远程用于把主仓库的最新改动合并进你的本地开发副本git remote add upstream Cirq 主仓库地址用git remote -v验证此时应同时看到origin与upstream两个远程。与upstream同步git fetch upstream可通过git ls-remote --branches upstream或git branch -r查看upstream上的分支最重要的是应能看到upstream/main。把 upstream 的 main 合并进本地 main保持最新git checkout main git merge upstream/main完成以上步骤后本地main就与 Cirq 主仓库的main保持同步可以开始基于它切分支开发了。2. 搭建开发环境基于 apt 的 Linux环境搭建共 6 步前 3 步完成后即可拥有一个带全部 dev tools 的隔离 Python 环境。2.1 安装系统依赖首先确保 Python 版本不低于 3.11python3 --version可查。其余系统依赖通过apt-get一次性安装。命令会拼接仓库根目录下两份清单文件的内容作为安装列表cat apt-system-requirements.txt dev_tools/conf/apt-list-dev-tools.txt | xargs sudo apt-get install --yes两份清单的实际内容如下apt-system-requirements.txtlatexmk、python3-tk、texlive-latex-extra——latex 相关工具用于渲染文档与 notebook 中的 LaTeX 公式dev_tools/conf/apt-list-dev-tools.txtshellcheckShell 脚本静态检查、virtualenvwrapper虚拟环境管理工具。注意如果后续修改了 Protocol Buffers还需要额外的步骤见本文第 4 节。2.2 配置 virtualenvwrappervirtualenvwrapper是上面安装的系统依赖之一它让你可以快速创建虚拟环境。如果此前未配置过需要把以下三行追加到~/.bashrc或~/.zshrc保存后新开终端或执行source ~/.bashrc激活export WORKON_HOME$HOME/.virtualenvs export VIRTUALENVWRAPPER_PYTHON/usr/bin/python3 source /usr/share/virtualenvwrapper/virtualenvwrapper.sh完整用法请参阅 virtualenvwrapper 官方文档。2.3 创建虚拟环境并安装开发依赖创建一个包含 Cirq 开发工具如 Mypy的 Python 虚拟环境mkvirtualenv cirq-py3 --python/usr/bin/python3 workon cirq-py3 python -m pip install --upgrade pip python -m pip install -r dev_tools/requirements/dev.env.txt之后每次新开终端只需workon cirq-py3即可重新激活该环境。注部分管理严格或定制过的设备可能与virtualenv冲突此时改用 anaconda 环境是更稳妥的选择。dev_tools/requirements/dev.env.txt 是一份完整开发环境清单其实际内容只有两行引用-r deps/cirq-all.txt -r deps/dev-tools.txt其中 deps/cirq-all.txt 汇总了全部模块含 contrib而 deps/dev-tools.txt 则继续引用mypy.txt、pytest.txt、format.txt、pylint.txt、protos.txt、notebook.txt、tensorflow-docs.txt、packaging.txt、ruff.txt并额外固定了qiskit-aer~0.17.0用于验证 QASM 输出行为与stimcirq用于测试 cirq-google 的 stimcirq 兼容性。requirements 文件之间的-r互相引用机制是去重的主要手段这一点在第 7 节还会展开。2.4 验证测试通过安装完成后先跑一遍全量测试确认环境正常./check/pytest .2.5可选把开发副本加入 Python 路径开发 Cirq 源码时通常希望import cirq直接命中本地代码有两种方式方式一source 脚本推荐bash 与 zsh 均可source dev_tools/pypathdev_tools/pypath 的实现值得一看它先通过dirname ${BASH_SOURCE[0]}定位脚本自身位置从而推导仓库根目录然后调用python dev_tools/modules.py list --mode folder列出所有模块的根文件夹再拼接成完整的PYTHONPATH前缀含cirq-core、cirq-google、cirq-ionq、cirq-aqt、cirq-pasqal、cirq-web等最后在已包含该前缀时才跳过重复设置。如果当前python不是 Python 3脚本会给出明确报错。方式二写入虚拟环境。先列出模块python dev_tools/modules.py listdev_tools/modules.py 是一个可作 CLI 亦可作库的工具list子命令支持--mode参数folder模块根目录如cirq-google、package-path顶层 Python 包路径如cirq-google/cirq_google、package顶层包名如cirq_google还支持--include-parent把 metapackage 一并纳入此外它还有print_version校验所有模块版本一致并打印与replace_version --old 旧版本 --new 新版本批量改写各模块_version.py与_version_test.py中的版本号两个子命令。把上一步输出的模块目录粘贴给add2virtualenvadd2virtualenv 粘贴上一步列出的模块add2virtualenv通常无法用xargs直接执行所以需要分两步。3. Editable 安装按模块安装而非装 metapackage如果希望用pip install的方式以可编辑editable模式安装 Cirq必须按模块逐个安装pip install -e ./cirq-core -e ./cirq-google -e ./cirq-ionq -e ./cirq-aqt这里有一个很容易踩的坑pip install -e .只会安装cirq这个 metapackage 本身你的代码改动不会被拾取。这是因为仓库采用多模块结构每个模块cirq-core、cirq-google等都有独立的setup.py与requirements.txtdeps/cirq-all-no-contrib.txt 中正是用-e ./cirq-aqt、-e ./cirq-core、-e ./cirq-google、-e ./cirq-ionq、-e ./cirq-pasqal、-e ./cirq-web的方式在 pip 层面一次性 editable 安装全部子包。4. Protocol Buffers修改后的重建流程Protocol Buffersprotobuf在 Cirq 中用于把电路、门及其他对象转换成标准形式便于其他程序读写。Cirq 的 proto 定义位于 cirq-google/cirq_google/api 下包含v1/与v2/两代 APIv2目录中可以看到program.proto、run_context.proto、result.proto、calibration.proto、device.proto、batch.proto、metrics.proto、ndarrays.proto等定义文件以及它们对应的生成产物*_pb2.py与*_pb2.pyi。如果更新了任何 proto其依赖产物可以通过脚本重建dev_tools/build-protos.shdev_tools/build-protos.sh 的实现揭示了完整生成链路进入cirq-google目录并定位tunits包的 proto 路径importlib.resources.files(tunits).parent该包为生成提供类型单位支持对cirq_google/api/v1与cirq_google/api/v2两个包分别执行python -m grpc_tools.protoc同时输出 Python 代码--python_out.与 mypy 桩--mypy_out.由于当前 protoc 生成的导入语句是绝对导入形式脚本最后用sed将其统一替换为相对导入from cirq.google.api.* import ...→from . import ...保证生成的*_pb2.py在包内可正常导入。生成所需的依赖来自 dev_tools/requirements/deps/protos.txtgrpcio-tools~1.78.0打包了 protoc 工具、mypy-protobuf~5.1.0生成 mypy 桩、typedunits。5. 持续集成与本地测试从快速检查到完整校验Cirq 提供从又快又方便到慢而可靠的多个检查层级。最朴素的方式是自行调用工具pytest pylint . mypy .但这种方式要求你已经用source dev_tools/pypath设置好 Python 路径。更省心的方式是使用 check/ 目录下的脚本——它们会自动设置 Python 路径与配置参数并覆盖更多场景。所有脚本都先通过git rev-parse --show-toplevel定位仓库根目录并cd过去因此可以从任意子目录执行。5.1 快速检查几秒到几十秒完成检查/应用代码格式仅针对变更行./check/format-incremental [--apply] [BASE_REVISION]check/format-incremental 内部会找出相对基线版本变更diff-filterMAR的*.py与*.ipynb排除*_pb2.py先用isort排序导入__init__.py除外再用black格式化默认只打印 diff 并以退出码 1 表示需要修改--apply才真正改写文件另支持--all检查全部文件。依赖见 dev_tools/requirements/deps/format.txtblack[jupyter]26.5.1、isort[colors]~8.0.1。Lint 检查ruff check ./check/pylint-changed-filesruff check直接调用 dev_tools/requirements/deps/ruff.txt 中固定的ruff0.15.15pylint-changed-files只对变更涉及的.py文件限定cirq、dev_tools、examples前缀排除cirq-google/cirq_google/cloud/*与*_pb2.py运行pylint --jobs0。运行与变更文件关联的测试./check/pytest-changed-files [BASE_REVISION]该脚本并不聪明它不解析文件间依赖只是把变更的x.py映射为x_test.py交给 pytest若修改了__init__.py还会额外纳入全局 API 序列化测试 cirq-core/cirq/protocols/json_serialization_test.py。同样pytest-changed-files-and-incremental-coverage在此基础上再对变更文件所在目录加--cov目录并调用python dev_tools/check_incremental_coverage_annotations.py分析覆盖率注释。运行 docstring 内嵌测试./check/doctest底层调用 dev_tools/docs/run_doctest.py它收集cirq**/cirq**/**/*.py下所有源码文件排除_test.py、cirq-google/cirq_google/api/等目录以doctest.ELLIPSIS选项执行 docstring 中的示例并预置cirq、cirq_google、np、pd、sympy等全局名字使示例无需显式导入即可运行。增量覆盖率只用与变更文件关联的测试./check/pytest-changed-files-and-incremental-coverage [BASE_REVISION]注意该检查比实际 CI 强制执行的增量覆盖率检查更严格——真实 CI 允许未关联文件的测试覆盖某些行。类型检查./check/typecheck [传给 mypy 的 flags]内部就是source dev_tools/pypath mypy $ .依赖 dev_tools/requirements/deps/mypy.txt 中的mypy2.1.0及types-protobuf、types-requests桩包。杂项检查./check/misc目前做两件事一是确保cirq.contrib之外的文件不引用cirq.contrib避免pip install cirq而非pip install cirq-core[contrib]的用户出错二是用git diff --checkcore.whitespaceincomplete-line检查空白错误与文件末尾换行。5.2 慢速检查每项数分钟运行全部测试./check/pytest [传给 pytest 的文件与 flags]check/pytest 默认以-nautopytest-xdist 并行运行若需单进程可传-n0最后的-n参数生效。pytest的依赖见 dev_tools/requirements/deps/pytest.txt包含pytest、pytest-asyncio、pytest-benchmark、pytest-cov、pytest-randomly、pytest-xdist、coverage~7.4等。全量 lint./check/pylint [传给 pylint 的 flags]即pylint --jobs0 $ .依赖 dev_tools/requirements/deps/pylint.txt 的pylint~4.0.2。增量覆盖率./check/pytest-and-incremental-coverage [BASE_REVISION]先check/pytest --cov全量跑测试并生成*.py,cover覆盖率注解文件再交给dev_tools/check_incremental_coverage_annotations.py base统计相对基线的未覆盖变更行最后用git clean -x -- *.py,cover清理中间产物。运行全部 CI 检查./check/all [BASE_REVISION] [--changed] [--fix]--changed让可聚焦的检查只针对变更文件以速度换准确性--fix自动应用 linter 与格式化工具的安全修正。check/all 的源码展示了真实的执行顺序依次运行check/misc、check/format-incremental、ruff check、pylint或pylint-changed-files、pytest-and-incremental-coverage或pytest-changed-files-and-incremental-coverage、check/typecheck最后在非--changed模式下再跑check/doctest注释解释doctest 很少失败但最耗时所以 only-changed 模式下跳过。任何一项失败都会被收集并在结束时汇总打印。脚本还提示--apply-format-changes已废弃应改用--fix。5.3 BASE_REVISION 的解析逻辑上文多个脚本的[BASE_REVISION]参数控制与哪个提交对比例如用于确定哪些文件变更。未指定时的默认优先级为upstream/main若存在origin/main若存在main实际用于对比的提交是基线与当前工作目录的git merge-base即最近公共祖先。注意上述脚本的结果可能与 GitHub 上的 CI 工作流不完全一致——例如你本地可能跑着旧版pylint或numpy。若需要针对真实 CI 验证请直接开一个 Pull Request可以以 draft 模式或标记为[Testing]以免被评审。6. 编写 docstring 与生成文档Cirq 使用Google style docstringsMarkdown 风格支持 LaTeX。关键规范含 LaTeX 的 docstring 应写成r-string原始字符串避免反斜杠被转义支持块级 LaTeX$$ ... $$与行内 LaTeX$y x^2$支持行内代码如cirq.unitary(cirq.X)标准段落包含Args:、Returns:、Raises:。仓库文档给出的完整示例def some_method(a: int, b: str) - float: rOne line summary of method. Additional information about the method, perhaps with some sort of LaTeX equation to make it clearer: $$ M \begin{bmatrix} 0 1 \\ 1 0 \end{bmatrix} $$ Notice that this docstring is an r-string, since the LaTeX has backslashes. We can also include example code: print(cirq_google.Sycamore) You can also do inline LaTeX like $y x^2$ and inline code like cirq.unitary(cirq.X). And of course theres the standard sections. Args: a: The first argument. b: Another argument. Returns: An important value. Raises: ValueError: The value of a wasnt quite right. docstring 中的示例由./check/doctest验证机制见第 5.1 节从而保证文档中的代码示例始终可运行。7. 依赖管理策略7.1 生产依赖模块内声明、保持宽松Cirq 采用模块化设计每个模块在自己目录下的requirements.txt中声明依赖例如 cirq-core/requirements.txt 与cirq-google/requirements.txt。以cirq-core为例运行期依赖包括attrs21.3.0、duet0.2.8、matplotlib~3.10、networkx~3.4、numpy~2.2、pandas2.3,3.1.0.dev、scipy~1.15、sympy、tqdm4.12。总体原则是依赖越少越好必须添加时尽量放宽版本约束而非精确 pin 死若确知精确版本或约束以注释形式说明。7.2 开发依赖一份全量清单 按 CI job 拆分本地开发使用 dev_tools/requirements/dev.env.txt 一次装齐所有模块依赖与全部 dev tools若嫌太重可只装 dev_tools/requirements/deps/dev-tools.txt 加对应模块依赖。持续集成则讲究按需安装每个 job 需要的依赖不同给每个小 job如单独的mypy检查都装完整 dev 环境太浪费因此在 dev_tools/requirements 下为每个 job 建立独立的job.env.txt只包含必要工具。仓库中现存的环境文件包括lint.env.txtcirq-all.txtpylint.txtruff.txt让 pylint 能检查依赖函数调用的实参mypy.env.txtcirq-all.txtmypy.txtnotebooks.env.txtcirq-all.txtpytest.txtnotebook.txtnotebook 测试的最小环境pytest-minimal.env.txtpytest.txtcirq-all-no-contrib.txtipython.txtpylint.txt用于pytest-changed-files的最小环境见 dev_tools/conf/pip-install-minimal-for-pytest-changed-files.shisolated-base.env.txtpytest.txtnotebook.txt隔离测试 notebook 与包的最小环境。requirements 文件之间可以互相-r包含这套机制被大量用于去重。要展开某个文件的所有约束扁平化输出使用仓库自带的工具python dev_tools/requirements/reqs.py dev_tools/requirements/dev.env.txtdev_tools/requirements/reqs.py 的实现很直观递归解析-r指令相对路径按当前文件所在目录解析按包含顺序输出每一行约束它自带测试用例 dev_tools/requirements/reqs_test.py配合test_data/下的a.req.txt、b.req.txt等样例可独立验证展开逻辑。8. 小结一份可落地的开发流程清单把以上内容串起来一个典型的 Cirq 开发周期是克隆/Forkgit clone主仓库或先 Fork 再添加upstream远程并git fetch upstreamgit merge upstream/main并配置blame.ignoreRevsFile .git-blame-ignore-revs建环境apt-get安装系统依赖 → 配置virtualenvwrapper→mkvirtualenv cirq-py3→pip install -r dev_tools/requirements/dev.env.txt→./check/pytest .验证开发source dev_tools/pypath或add2virtualenv让本地代码生效按模块pip install -e ./cirq-*做 editable 安装改动 proto 时运行dev_tools/build-protos.sh提交前自检./check/format-incremental --apply、ruff check、./check/pylint-changed-files、./check/pytest-changed-files、./check/doctest、./check/typecheck、./check/misc等快速检查全面验证合并前跑./check/all必要时加--changed提速或--fix自动修正并以upstream/main为基线解读增量覆盖率结果。这套流程既覆盖了仓库文档定义的开发者任务全集也与 check/ 各脚本、dev_tools 工具链的真实实现一一对应可以作为日常开发与提交评审的可靠参照。赞分享科学计算【免费下载链接】CirqPython framework for creating, editing, and running Noisy Intermediate-Scale Quantum (NISQ) circuits.项目地址https://gitcode.com/gh_mirrors/ci/Cirq点击查看免费下载相关推荐handson-ml3 环境搭建完整指南从克隆仓库到运行 Jupyter Notebook 的 Anaconda 实战手册handson ml3 环境搭建完整指南从克隆仓库到运行 Jupyter Notebook 的 Anaconda 实战手册 导读 本指南围绕《Hands On示例工程教程AI-For-Beginners 环境搭建与运行故障排查指南从仓库克隆到 Notebook 实战的完整排障手册AI For Beginners 环境搭建与运行故障排查指南从仓库克隆到 Notebook 实战的完整排障手册 本指南以《AI For Beginners 故教程人工智能机器学习深度学习Code Blocks与highlight.js揭秘Google Docs代码高亮背后的技术原理Code Blocks与highlight.js揭秘Google Docs代码高亮背后的技术原理 想要在Google Docs文档中优雅地展示代码片段吗Co上一篇【亲测免费】 Pulovers Macro Creator 常见问题解决方案下一篇Icepick开源项目常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考