Swift Numerics（Swift数值计算库）

简介

Swift Numerics 提供了一组支持 Swift 中数值计算的模块。这些模块大致分为两类：

这两类之间存在一些重叠，并且第一类中的 API 可能会随着成熟和新用途的发现而迁移到第二类。

Swift Numerics 模块是细粒度的。例如，如果您需要对复数的支持，您可以导入 ComplexModule1 作为一个独立的模块

import ComplexModule

let z = Complex<Double>.i

还有一个顶层 Numerics 模块，它重新导出 Swift Numerics 的完整公共接口

import Numerics

// The entire Swift Numerics API is now available

Swift Numerics 模块对其他项目的依赖性最小。

当前的模块仅假定 Swift 和 C 标准库以及 compiler-rt 提供的运行时支持可用。

未来的扩展可能会假定其他标准接口的可用性，例如 BLAS (基本线性代数子程序) 和 LAPACK (线性代数包)，但具有更专门依赖项（或在 Swift 支持的所有平台上不可用的依赖项）的模块属于单独的软件包。

因为我们打算在未来的某个时刻使 Swift Numerics 模块能够被标准库采用，所以 Swift Numerics 使用与 Swift 项目相同的许可证和贡献指南。

在您的项目中使用 Swift Numerics

要在 SwiftPM 项目中使用 Swift Numerics

  1. 将以下行添加到您的 Package.swift 文件中的 dependencies 中
.package(url: "https://github.com/apple/swift-numerics", from: "1.0.0"),
  1. 将 Numerics 添加为目标的依赖项
.target(name: "MyTarget", dependencies: [
  .product(name: "Numerics", package: "swift-numerics"),
  "AnotherModule"
]),
  1. 在您的源代码中添加 import Numerics。

源代码稳定性

Swift Numerics 包是源代码稳定的；版本号遵循 语义化版本控制。 swift-numerics 包的公共 API 由顶层 Numerics 模块重新导出的模块中标记为 public 或 usableFromInline 的非下划线声明组成。 不属于公共 API 的接口可能会在任何版本（包括补丁版本）中继续更改。

请注意，_NumericsShims 和 _TestSupport 模块的内容以及 Tests 目录的内容，明确地不是公共 API。 因此，其中的定义可能会随意更改，并且整个模块可能会在任何新版本中删除。 如果您有需要下划线操作的用例，请提出问题，要求将其设为公共 API。

该软件包未来的次要版本可能会根据需要对这些规则进行更改。

我们希望该软件包能够快速采用与它的任务相关的 Swift 语言和工具链改进。 因此，我们预计该软件包的新版本会不时要求客户端升级到更新的 Swift 工具链版本。 需要新的 Swift 版本只需要次要版本更新。

贡献 Swift Numerics

Swift Numerics 是一个独立的库，与核心 Swift 项目分离，但有时它将充当 API 的过渡地带，这些 API 稍后将被合并到 Swift 标准库中。 发生这种情况时，此类更改将使用 Swift 项目的既定演进过程提交给 Swift 标准库。

Swift Numerics 使用 GitHub issues 来跟踪错误和功能。 我们使用 pull requests 进行开发。

如何提议一个新模块

  1. 提出带有 [new module] 标签的 issue。
  2. 提出带有实现草图的 PR。
  3. 一旦您达成共识，请让管理员创建一个特性分支，可以针对该分支提出 PR。
  4. 当设计稳定并且功能足够有用时，提出一个 PR 以将新模块合并到 master。

如何为现有模块提议一个新功能

  1. 提出带有 [enhancement] 标签的 issue。
  2. 提出带有您的实现的 PR，并在那里讨论实现。
  3. 一旦达成共识，认为新功能是可取的，并且设计是合适的，就可以合并它。

如何修复错误或进行较小的改进

  1. 提出带有您的更改的 PR。
  2. 确保为您所做的任何更改添加测试覆盖率。

论坛

有关如何使用 Swift Numerics 模块的问题，或不明显的错误问题可以在 Swift 论坛的“Swift Numerics”部分中进行讨论。

模块

  1. RealModule
  2. ComplexModule
  3. IntegerUtilities (仅在 main 上，尚未出现在已发布的标记中)

未来扩展

  1. 大固定宽度整数
  2. 任意精度整数
  3. 形状数组
  4. 十进制浮点数

脚注

  1. 该模块被命名为 ComplexModule 而不是 Complex，因为当类型和模块具有相同的名称时，Swift 当前无法使用类型的完全限定名称（此处讨论：https://forums.swift.org/t/pitch-fully-qualified-name-syntax/28482)。 这将阻止不需要泛型类型的 Swift Numerics 用户执行以下操作，例如

    import Complex
// I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
typealias Complex = Complex.Complex<Double> // This doesn't work, because name lookup fails.

    因此，在这种情况下，Swift Numerics 中具有这种歧义的模块都添加了 Module 后缀

    import ComplexModule
// I know I only ever want Complex<Double>, so I shouldn't need the generic parameter.
typealias Complex = ComplexModule.Complex<Double>
// But I can still refer to the generic type by qualifying the name if I need it occasionally:
let a = ComplexModule.Complex<Float>

    Real 模块不包含 Real 类型，但包含 Real 协议。 用户可能想要定义他们自己的 Real 类型（并且可能重新导出 Real 模块） - 这就是也应用该后缀的原因。 新模块必须仔细评估此决定，但可以放心地添加后缀。 预计大多数用户只会 import Numerics，因此这对他们来说不是问题。 ↩