3. 贡献Python代码#

3.1. 介绍#

如果你是一个有经验的程序员，你可能想要帮助开发新功能或修复skscope库中的错误。在这里，我们将介绍一个通用的工作流程，以便于你的贡献。

3.2. 贡献之前#

在贡献之前，我们强烈建议您对以下列出的要点进行自我检查。

  • 你可以随时打开一个issue，并确保abess-team中的某个人同意它确实有贡献性。我们不希望你花大量时间在我们正在处理的事情上，或者我们认为不是一个好主意的事情上。

  • 通过点击页面右上角的“Fork”按钮来分叉主仓库，这将在您的GitHub账户中创建一个副本。

  • 如果你已经分叉了skscope仓库，进入它并点击“Fetch upsteam”，然后点击“Fetch and merge”以确保代码是最新的

  • 将 skscope 克隆到本地计算机：

    git clone https://github.com/your_account_name/skscope.git
cd skscope

  • 通过遵循安装说明在github上使用代码安装skscope；

3.3. 通用工作流程#

以下是首选的工作流程。

  1. 开发用于提供新功能或解决报告错误的python代码。

  2. 此外，您应将相关测试代码添加到pytest目录中并进行自动化测试：

    cd pytest
pytest .

确保新功能正常工作或错误得到妥善解决。

  1. 重复步骤1-2，直到pytest .不再引发任何错误。一旦完成步骤3，意味着Python代码开发已完成。

要完成工作流程，您应首先将它们推送到您的存储库：

git add changed_files
git commit -m "YourContributionSummary"
git push

接下来，回到GitHub，通过点击你fork的“Contribute”按钮来打开pull request，将你的代码与skscope中的最新代码合并。然后，我们将收到你的贡献。

3.4. 开发一个新的求解器#

在这一部分，我们特别关注开发快速稀疏约束优化（SCO）求解器的新特性。我们将说明一个推荐的开发SCO求解器的程序，以便您的实现在skscope框架下流畅运行。潜在的求解器可能包括：

  • 牛顿硬阈值阈值化 [1],

  • 快速迭代收缩阈值算法 (FISTA) [2],

等等。在下面，我们将以FISTA为例，展示开发新求解器的过程。

3.4.1. 实现一个新的求解器#

首先，在skscope中创建一个新的python文件，例如skscope/fista.py，该文件包含此方法的实现。在这个python文件中，代码的草图如下所示。

# new algorithms should inherit the base class `BaseSolver`
from .base_solver import BaseSolver

class NewSolver(BaseSolver):
   """
   Introduction about the new algorithm
   """
   def __init__(self, ...):
      super(NewSolver, self).__init__(
         step_size=0.0005,
         # other init
      )

   def _solve(
      self,
      sparsity,
      loss_fn,
      value_and_grad,
      init_support_set,
      init_params,
      data,
   ):
   # Implement the core iterative procedure of the new algorithm

BaseSolver 实现了一些通用函数，这些函数在检查输入和提取计算结果方面发挥作用。实现后，不要忘记在 skscope/__init__.py 中导入新算法。

现在再次运行 pip install -e .，这次安装会很快完成。恭喜！你的工作现在可以被以下方式使用：

from skscope import NewSolver

3.4.2. 测试求解器#

编写代码后，需要验证贡献的求解器是否能返回合理的结果。在这里，我们分享我们的经验。

  1. 测试压缩感知问题的求解器。

3.4.3. 记录求解器#

贡献几乎完成了。剩下的工作是为这个求解器添加一份文档。一个新的求解器需要简短的介绍和一些示例。还要注意，Python文档的风格类似于numpydoc。

Python API文档的开发主要依赖于 Sphinx、sphinx-gallery（支持Sphinx的markdown）、pydata-sphinx-theme （支持Sphinx的“Read the Docs”主题）等。请确保docs/requirements.txt中的所有包都已通过以下方式安装：

pip install -r docs/requirements.txt

3.6. 参考#

  • [1] 周, S., 修, N., & 齐, H. D. (2021). 牛顿硬阈值追踪的全局和二次收敛性. 机器学习研究杂志, 22(1), 599-643.

  • [2] Beck, A., & Teboulle, M. (2009). 一种用于线性逆问题的快速迭代收缩阈值算法。SIAM 成像科学杂志，2(1), 183-202.