为 ZOSPy 做出贡献

为 ZOSPy 做出贡献#

感谢您考虑为ZOSPy做出贡献！在做出贡献之前，请阅读这些指南，以便我们尽快处理您的贡献。

贡献想法#

ZOSPy旨在通过为OpticStudio API提供Pythonic接口，使 Python 和 Zemax/Ansys OpticStudio 之间的交互尽可能简单。欢迎任何服务于此目标或帮助OpticStudio进行光学模拟的贡献。如果您不知道该贡献什么，以下是一些绝对受欢迎的想法：

  1. 各种光学系统的示例（在examples/中）。这些必须以Jupyter Notebook的形式提供；

  2. 实现额外的分析（在zospy/analyses中）。请参阅其他分析以了解如何实现它们。如果您添加新的分析，请同时包含单元测试；

  3. 附加求解器的实现（在zospy/solvers中）。

代码风格#

  • 请根据numpydoc格式化您的文档字符串。

  • 使用ruff检查并格式化你的代码。

所有格式均可自动应用（见下文）。提交 Pull 请求时将检查是否遵守这些准则。

工作流#

1. 设置开发环境#

ZOSPy 使用Hatch进行项目管理。要开始ZOSPy开发，请安装Hatch：

  • [在Windows上安装 Hatch]

或者，您可以使用uv或pipx安装 Hatch：

# Using uv
uv tool install hatch

# Using pipx
pipx install hatch

接下来，打开项目目录并运行以下命令来设置开发环境：

hatch env create

2. 添加新功能#

在新的功能分支中添加您的贡献。贡献分析时，请包含单元测试。

3. 格式化代码#

要格式化代码，请在项目目录中运行以下命令：

hatch fmt

要格式化文档字符串，请运行以下命令：

hatch run format-docstrings

4. 测试#

由于依赖OpticStudio，无法使用GitHub Actions进行自动测试，因此我们要求您在打开Pull请求之前运行所有单元测试。已针对多个Python版本实现了自动测试，可以通过运行以下命令启动

hatch test

在项目目录中。有关运行单元测试的更多信息，请参见此处。如果您运行以前未测试过的OpticStudio版本的测试或为分析包装器添加测试，请不要忘记为这些测试生成参考数据。有关此内容的更多信息，请参见测试文档。

5. 打开Pull请求#

打开一个拉取请求，等待我们的建议，并合并您的贡献！

目录