PyFstat

这是一个Python包，提供了一个基于LALSuite库的F统计量连续引力波（CW）搜索的接口。

入门

• 此README提供了有关安装、贡献和引用PyFstat的信息。
• PyFstat 的使用方法和其 API 文档可在 pyfstat.readthedocs.io 查找。
• 我们还提供了一些 教程 和 示例，展示了不同的使用场景。您可以在本地运行它们，或者通过 binder 在线运行。
• 项目维基主要用于开发者信息。
• 还有一个 变更日志 可用。
• PyFstat >=2.0.0 需要 LALSuite (>=7.13) / lalpulsar (>=6.0)，包括 SFTv3 规范。如果您需要使用旧版本，最后一个支持这些版本的 PyFstat 发布版是 1.19.1。

安装

PyFstat 发布版可以通过多种方式安装，包括从 PyPI 使用 pip install、conda、Docker/Singularity 镜像以及从 Zenodo 上的源发布版 安装。最新的开发版本也可以通过 pip 安装 或从本地 git 克隆 安装。

如果您系统上没有匹配的 python 安装（目前为 3.9 到 3.12），那么使用 Docker 或 conda 是最简单的途径。

在任何情况下，请务必查看关于 依赖项 和 引用这项工作 的说明。

如果在使用星历文件时遇到问题，请查看 星历安装 的维基页面。

从 PyPI 使用 pip 安装

PyPI 发布版可在 https://pypi.ac.cn/project/PyFstat/ 获取。

一个简单的

pip install pyfstat

命令将为您提供包含所有依赖项的最新发布版本；最近的发布版本现在还包括（或通过依赖项拉入）足够的最小星历文件集。

如果您没有在 venv 或 conda 环境 中安装（您真的应该这样做！），在许多系统中，您可能需要使用 --user 标志。

请注意，如果您的 pip 太旧（例如 18.1），PyFstat 安装将在 LALSuite 依赖项阶段失败；要修复此问题，请执行以下操作：

pip install --upgrade pip setuptools

conda 安装

有关安装 conda 本身、将 PyFstat 安装到现有环境或设置 PyFstat 特定环境的 .yml 脚本（适用于普通用户和开发者）的进一步说明，请参阅 此维基页面。

如果从 conda-forge 获取 PyFstat，它已经包含了所需的星历文件。

Docker 容器

预置的 PyFstat 容器可在 软件包 页面上找到。需要 GitHub 账户和个人访问令牌。有关如何使用 Docker 或 Singularity 从 GitHub 仓库拉取它们的说明，请参阅 维基页面。

从 GitHub 使用 pip 安装

通过直接将 pip 指向此 git 仓库，可以轻松安装 PyFstat 的开发版本，这将为您提供 master 分支的最新版本

pip install git+https://github.com/PyFstat/PyFstat

或者，如果您已在 github 上安装了 ssh 密钥

pip install git+ssh://git@github.com/PyFstat/PyFstat

这将以与从 PyPI 安装相同的方式拉入所有依赖项。

从源（Zenodo 或 git 克隆）安装 PyFstat

您可以从Zenodo下载源代码压缩包，并将其解压到任意临时目录中。或者，克隆这个仓库。

git clone https://github.com/PyFstat/PyFstat.git

假设您处于（解压或克隆）源代码目录中，可以通过以下方式全局安装（或安装到当前活动虚拟环境中）模块和相关脚本。

python setup.py install

作为开发者，另一种方法

python setup.py develop

或者

pip install -e /path/to/PyFstat

这可能很有用，您可以直接看到您所做的任何更改。或者（不建议这样做！），将源代码目录直接添加到您的Python路径中。

要检查安装是否成功，请运行

python -c 'import pyfstat'

如果没有输出错误消息，则表示您已安装pyfstat。请注意，模块将安装到您从中调用的任何Python可执行文件。

这将以与从 PyPI 安装相同的方式拉入所有依赖项。

依赖项

PyFstat使用以下外部Python模块，如果您使用pip，它们都应该自动安装

• corner
• dill
• lalsuite
• matplotlib
• numpy
• pathos
• ptemcee
• scipy
• solar-system-ephemerides（从lalsuite>7.15开始）
• tqdm
• versioneer

有关安装模块的一般介绍，请参阅此处。

注意：目前我们已将numpy<2.0锁定（与LALSuite相同）。

注意：我们要求使用最新的LALSuite（>=7.13）/ lalpulsar（>=6.0）。如果您需要处理旧版本，最后一个支持这些版本的PyFstat版本是1.19.1。

注意：通过pip，我们安装依赖项lalsuite[lalpulsar]。对于lalsuite <= 7.15，可选标志[lalpulsar]被忽略，因为这些版本包含自己的摄动数据。对于lalsuite > 7.15，[lalpulsar]安装solar-system-ephemerides，并使用此辅助包来访问摄动数据。

可选依赖项

PyFstat通过setuptool的extras_require管理可选依赖项。

可用的可选依赖项集合是

• chainconsumer (Samreay/ChainConsumer)：运行某些可选绘图方法和一些示例脚本所必需的。
• dev：收集docs、style、test和wheel。
• docs：构建文档所需的必需依赖项。
• pycuda (PyPI)：对于TransientGridSearch类的tCWFstatMapVersion=pycuda选项是必需的。（注意：安装pycuda需要路径中存在有效的nvcc编译器。）
• style：包括flake8代码检查器（flake8.pycqa）、black代码风格检查器（black.readthedocs）和isort导入排序（pycqa.github.io）。这些检查是必须通过在线集成管道的。
• test：用于在本地使用pytest及其一些附加组件运行测试套件。（注意：运行测试套件使用python -m pytest tests/）。
• wheel：包括wheel和check-wheel-contents。

可以通过将上述一个或多个标签添加到安装命令中来进行安装。

例如，安装包含chainconsumer、pycuda和style依赖项的PyFstat的命令如下（注意空格的缺失！）

pip install pyfstat[chainconsumer,pycuda,style]

此命令接受“开发模式”标签-e。

请注意，LALSuite是默认要求，而不是可选的，但可以通过设置环境变量NO_LALSUITE_FROM_PYPI来禁用从PyPI安装LALSuite，例如，从本地git克隆的开发安装

NO_LALSUITE_FROM_PYPI=1 pip install -e .

这可以避免在conda环境中或在从源代码安装LALSuite时出现重复。

使用从源代码构建的LALSuite

有关使用自定义本地LALSuite安装的说明，请参阅维基上的此处。

为PyFstat做出贡献

本项目对开发开放，请随时联系我们咨询或直接提交问题或拉取请求。

以下是需要了解的内容

• 作为开发者，您应直接从git克隆安装，使用pip install -e .[dev]在某环境或直接从pyfstat-dev.yml文件创建一个启用开发的conda环境，如此维基页面上所述。请确保在安装后运行一次

  pre-commit install
  

  这将为自动化的代码质量测试（见下文）设置一切，以便在每次提交时为您检查。

• GitHub的自动化测试目前运行在python [3.9,3.10,3.11,3.12]，新的PR需要通过所有这些。

• 您也可以通过pytest tests/在本地上运行完整的测试套件，或者按照此页面上的说明运行单个测试。

• GitHub上的自动化测试还运行了black样式检查器、flake8代码检查器和isort导入排序助手。

• 如果您已正确通过pip或conda安装了开发依赖项，并且已运行一次pre-commit install，则可以准备让pre-commit工具在每次执行git commit时自动为您完成所有这些操作。对于GitHub集成测试中会失败的任何内容，它将自动重新格式化您的代码以匹配我们的样式，或者打印警告以修复问题。第一次设置可能需要一段时间，之后应该会更快。

• 如果您由于某些原因无法使用pre-commit，您在推送更改/提交PR之前仍然可以手动运行这些工具：使用isort .排序包导入，使用flake8 --count --statistics .查找常见的编码错误并手动修复，使用black --check --diff .显示所需的样式更改，或者使用black .自动应用它们。

贡献者

维护者

• Greg Ashton
• David Keitel

活跃贡献者

• Reinhard Prix
• Rodrigo Tenorio

其他贡献者

• Karl Wette
• Sylvia Zhu
• Dan Foreman-Mackey（《pyfstat.gridcorner》基于DFM的corner.py）

引用此工作

如果您在出版物中使用PyFstat，我们将非常感谢您引用软件本身的发布DOI（见下文）以及以下科学论文中的一篇或几篇

• 总结该包的最近JOSS（开源软件杂志）论文：Keitel, Tenorio, Ashton & Prix 2021 (inspire:1842895 / ADS:2021arXiv210110915K)。
• 介绍该包和MCMC功能的原始论文：Ashton & Prix 2018 (inspire:1655200 / ADS:2018PhRvD..97j3020A)。
• 介绍用于评估多阶段后续处理的贝叶斯因子的方法论文：Tenorio, Keitel, Sintes 2021 (inspire:1865975 / ADS:2021PhRvD.104h4012T)
• 用于瞬态搜索：Keitel & Ashton 2018 (inspire:1673205 / ADS:2018CQGra..35t5003K)。
• 用于故障鲁棒性搜索：Ashton, Prix & Jones 2018 (inspire:1672396 / ADS:2018PhRvD..98f3011A)

如果您还想一般性地引用 PyFstat 包，请参考以下版本无关的 Zenodo 列表 版本无关的 Zenodo 列表 或直接使用以下 BibTeX 条目

@misc{pyfstat,
  author       = {Ashton, Gregory and
                  Keitel, David and
                  Prix, Reinhard
                  and Tenorio, Rodrigo},
  title        = {{PyFstat}},
  month        = jul,
  year         = 2020,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.3967045},
  url          = {https://doi.org/10.5281/zenodo.3967045},
  note         = {\url{https://doi.org/10.5281/zenodo.3967045}}
}

您还可以从 Zenodo 的右侧边栏获取各个版本发行版的 DOI（从 1.5.x 开始）。

或者，如果您在作品中使用了 PyFstat 的 1.4.x 或更低版本，这些版本的 DOI 可以在以下较旧的 Zenodo 记录的侧边栏中找到 这个较旧的 Zenodo 记录，并请相应地修改 BibTeX 条目。

PyFstat 使用了 ptemcee 采样器，可引用为 Vousden, Far & Mandel 2015（《ADS:2016MNRAS.455.1919V》）和 Foreman-Mackey, Hogg, Lang, and Goodman 2012（《2013PASP..125..306F》）。

PyFstat 还大量使用了 LALSuite 库的功能，通常也适合引用该项目（参见 此推荐 BibTeX 条目）以及 Wette 2020（《inspire:1837108）/《ADS:2020SoftX..1200634W》）关于 C-to-python SWIG 绑定。