From eb76aa632b7a73c1b1c66ac17c6dec8bae57cde4 Mon Sep 17 00:00:00 2001 From: Stephen Canon Date: Wed, 30 Oct 2019 16:11:20 -0400 Subject: [PATCH] Update license headers, add CONTRIBUTING.md and umbrella module --- CONTRIBUTING.md | 9 ++++ Package.swift | 7 +-- README.md | 52 ++++++++++++------- Sources/Complex/Arithmetic.swift | 9 ++-- Sources/Complex/Complex.swift | 5 +- Sources/Complex/README.md | 2 +- .../ElementaryFunctions.swift | 5 +- .../ElementaryFunctions/Implementations.swift | 5 +- Sources/ElementaryFunctions/README.md | 6 +-- .../ScalarConformances.swift | 5 +- Sources/Numerics/Numerics.swift | 14 +++++ Sources/NumericsShims/NumericsShims.c | 5 +- Sources/NumericsShims/include/NumericsShims.h | 5 +- Tests/ComplexTests/ComplexTests.swift | 5 +- .../ElementaryFunctionTests.swift | 5 +- 15 files changed, 84 insertions(+), 55 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 Sources/Numerics/Numerics.swift diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4ed4dbd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +By submitting a pull request, you represent that you have the right to license your +contribution to Apple and the community, and agree by submitting the patch that +your contributions are licensed under the [Swift license](https://swift.org/LICENSE.txt). + +--- + +Before submitting the pull request, please make sure you have tested your changes +and that they follow the Swift project [guidelines for contributing +code](https://swift.org/contributing/#contributing-code). diff --git a/Package.swift b/Package.swift index 7f009ac..e7d6c85 100644 --- a/Package.swift +++ b/Package.swift @@ -1,13 +1,12 @@ // swift-tools-version:5.0 //===--- Package.swift ----------------------------------------*- swift -*-===// // -// This source file is part of the Swift.org open source project +// This source file is part of the Swift Numerics open source project // -// Copyright (c) 2019 Apple Inc. and the Swift project authors +// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors // Licensed under Apache License v2.0 with Runtime Library Exception // // See https://swift.org/LICENSE.txt for license information -// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors // //===----------------------------------------------------------------------===// @@ -18,12 +17,14 @@ let package = Package( products: [ .library(name: "Complex", targets: ["Complex"]), .library(name: "ElementaryFunctions", targets: ["ElementaryFunctions"]), + .library(name: "Numerics", targets: ["Numerics"]), ], dependencies: [ ], targets: [ .target(name: "Complex", dependencies: ["ElementaryFunctions"]), .target(name: "ElementaryFunctions", dependencies: ["NumericsShims"]), + .target(name: "Numerics", dependencies: ["Complex", "ElementaryFunctions"]), .target(name: "NumericsShims", dependencies: []), .testTarget(name: "ComplexTests", dependencies: ["Complex"]), diff --git a/README.md b/README.md index 67bf4bb..c1f2152 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -# Swift-Numerics +# Swift Numerics ## Introduction -Swift-numerics provides a set of modules that support numerical computing in Swift. +Swift Numerics provides a set of modules that support numerical computing in Swift. These modules fall broadly in two categories: - API that is too specialized to go into the standard library, but which is sufficiently @@ -12,24 +12,34 @@ standard library. There is some overlap between these two categories, and API that begins in the first category may migrate to the second as it matures and new uses are discovered. -Swift-numerics modules are fine-grained; if a user needs support for Complex numbers, -they can import the Complex module without pulling in a module for linear algebra as well. +Swift Numerics modules are fine-grained; if a user needs support for Complex numbers, +they can import the Complex module without pulling in a module for linear algebra as +well. However, there is also a top-level `Numerics` module that simply re-exports all of +the public modules of the library. -Swift-numerics modules have minimal dependencies on other projects. It assumes only -the availability of the Swift and C standard libraries, and the runtime support provided -by compiler-rt. Future expansion may assume the availability of other standard -interfaces such as BLAS and LAPACK, but modules with more specialized -dependencies probably belong in a separate package. +Swift Numerics modules have minimal dependencies on other projects. The current +modules assume only the availability of the Swift and C standard libraries, and the +runtime support provided by compiler-rt. Future expansion may assume the availability +of other standard interfaces such as BLAS and LAPACK, but modules with more +specialized dependencies (or dependencies that are not available on all platforms +supported by Swift) belong in a separate package. ## Process -Swift-numerics changes are not expected to go through swift-evolution. For some -modules, swift-numerics may act as a staging area for the standard library, but in -those cases, the expectation is that swift-evolution review will take place at the point -that the module is proposed for inclusion. It's good to keep that process in mind, -however, and document *why* you're making the decisions that you are, so that -reviewers can refer to those rationales when a module comes up for swift-evolution. +Swift Numerics is a standalone library separate from the core Swift project. In practice +it will act as a staging ground for some APIs that may eventually be incorporated into +the Swift Standard Library, and when that happens such changes will be proposed +to the Swift Standard Library using the established evolution process of the Swift +project. -Swift-numerics uses github issues to track bugs and features, and pull requests for +It's practice to keep this process in mind, and document *why* you're making the +decisions that you are, so that reviewers can refer to those rationales if a module +comes up for Swift Evolution in the future. + +Because our intention is to make it possible to adopt Swift Numerics modules in the +standard library at some future point, Swift Numerics uses the same license and +contribution guidelines as the Swift project. + +Swift Numerics uses github issues to track bugs and features, and pull requests for development. To propose a new module: @@ -47,7 +57,11 @@ To propose a new feature for an existing module: it can be merged. To fix a bug, or make smaller improvements: -1. Raise a PR with your change. Be sure to add test coverage for whatever changes you are making. +1. Raise a PR with your change. Be sure to add test coverage for whatever changes +you are making. + +Questions about how to use Swift Numerics modules, or issues that are not clearly +bugs can be discussed in the "Swift Numerics" section of the Swift forums. ## Modules 1. [ElementaryFunctions](Sources/ElementaryFunctions/README.md) @@ -58,5 +72,5 @@ To fix a bug, or make smaller improvements: 2. [Large Fixed-Width Integers](https://github.com/apple/swift-numerics/issues/4) 3. [Arbitrary-Precision Integers](https://github.com/apple/swift-numerics/issues/5) 4. [Shaped Arrays](https://github.com/apple/swift-numerics/issues/6) -4. [Decimal Floating-point](https://github.com/apple/swift-numerics/issues/7) -5. [Float16](https://github.com/apple/swift-numerics/issues/8) +5. [Decimal Floating-point](https://github.com/apple/swift-numerics/issues/7) +6. [Float16](https://github.com/apple/swift-numerics/issues/8) diff --git a/Sources/Complex/Arithmetic.swift b/Sources/Complex/Arithmetic.swift index b3213b2..403dead 100644 --- a/Sources/Complex/Arithmetic.swift +++ b/Sources/Complex/Arithmetic.swift @@ -1,12 +1,11 @@ //===--- Arithmetic.swift -------------------------------------*- swift -*-===// // -// This source file is part of the Swift.org open source project +// This source file is part of the Swift Numerics open source project // -// Copyright (c) 2019 Apple Inc. and the Swift project authors +// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors // Licensed under Apache License v2.0 with Runtime Library Exception // // See https://swift.org/LICENSE.txt for license information -// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors // //===----------------------------------------------------------------------===// @@ -74,7 +73,7 @@ extension Complex: Numeric { // Try the naive expression z/w = z*conj(w) / |w|^2; if the result is // normal, then everything was fine, and we can simply return the result. let naive = z * w.conjugate.divided(by: w.unsafeLengthSquared) - guard naive.isNormal else { return carefulDivide(z, w) } + guard naive.isNormal else { return rescaledDivide(z, w) } return naive } @@ -89,7 +88,7 @@ extension Complex: Numeric { } @usableFromInline - internal static func carefulDivide(_ z: Complex, _ w: Complex) -> Complex { + internal static func rescaledDivide(_ z: Complex, _ w: Complex) -> Complex { if z.isZero || !w.isFinite { return .zero } let zScale = z.magnitude let wScale = w.magnitude diff --git a/Sources/Complex/Complex.swift b/Sources/Complex/Complex.swift index 6663ac6..533657b 100644 --- a/Sources/Complex/Complex.swift +++ b/Sources/Complex/Complex.swift @@ -1,12 +1,11 @@ //===--- Complex.swift ----------------------------------------*- swift -*-===// // -// This source file is part of the Swift.org open source project +// This source file is part of the Swift Numerics open source project // -// Copyright (c) 2019 Apple Inc. and the Swift project authors +// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors // Licensed under Apache License v2.0 with Runtime Library Exception // // See https://swift.org/LICENSE.txt for license information -// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors // //===----------------------------------------------------------------------===// diff --git a/Sources/Complex/README.md b/Sources/Complex/README.md index 487fa6f..d312ed0 100644 --- a/Sources/Complex/README.md +++ b/Sources/Complex/README.md @@ -48,7 +48,7 @@ This is a show-stopper for heterogeneous arithmetic operators in the short term. ### Infinity and nan C and C++ attempt to define precise semantics that interpret the sign of infinity and zero. -This is occasionally useful, but it also results in a lot of extra work. The swift-numerics +This is occasionally useful, but it also results in a lot of extra work. The Swift Numerics `Complex` type does not assign any semantic meaning to the sign of zero and infinity; `(±0,±0)`, are all considered to be encodings of the value zero. Similarly, `(±inf, y)`, `(x, ±inf)`, `(nan, y)` and `(x, nan)` are all considered to be encodings of a single diff --git a/Sources/ElementaryFunctions/ElementaryFunctions.swift b/Sources/ElementaryFunctions/ElementaryFunctions.swift index 4653a0f..d6fad81 100644 --- a/Sources/ElementaryFunctions/ElementaryFunctions.swift +++ b/Sources/ElementaryFunctions/ElementaryFunctions.swift @@ -1,12 +1,11 @@ //===--- ElementaryFunctions.swift ----------------------------*- swift -*-===// // -// This source file is part of the Swift.org open source project +// This source file is part of the Swift Numerics open source project // -// Copyright (c) 2019 Apple Inc. and the Swift project authors +// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors // Licensed under Apache License v2.0 with Runtime Library Exception // // See https://swift.org/LICENSE.txt for license information -// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors // //===----------------------------------------------------------------------===// diff --git a/Sources/ElementaryFunctions/Implementations.swift b/Sources/ElementaryFunctions/Implementations.swift index 2b890eb..c8dbab1 100644 --- a/Sources/ElementaryFunctions/Implementations.swift +++ b/Sources/ElementaryFunctions/Implementations.swift @@ -1,12 +1,11 @@ //===--- Implementations.swift --------------------------------*- swift -*-===// // -// This source file is part of the Swift.org open source project +// This source file is part of the Swift Numerics open source project // -// Copyright (c) 2019 Apple Inc. and the Swift project authors +// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors // Licensed under Apache License v2.0 with Runtime Library Exception // // See https://swift.org/LICENSE.txt for license information -// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors // //===----------------------------------------------------------------------===// diff --git a/Sources/ElementaryFunctions/README.md b/Sources/ElementaryFunctions/README.md index 7c30719..b17ad31 100644 --- a/Sources/ElementaryFunctions/README.md +++ b/Sources/ElementaryFunctions/README.md @@ -1,7 +1,7 @@ # Elementary Functions -This module implements [SE-0246]. It is being implemented here first to work around a -few difficulties that blocked adding these operations to the standard library for 5.1: +This module implements [SE-0246]. It is implemented in Swift Numerics to work +around difficulties that blocked adding these operations to the standard library for 5.1: - Swift does not yet have a way to back-deploy protocol conformances; this prevents making this useful feature available on older Apple OS targets. @@ -18,7 +18,7 @@ See https://github.com/apple/swift/pull/25316 for discussion of how to fix this. - There are some typechecker performance regressions (partially resulting from the issues described above). -Placing this module in swift-numerics first gives the community a chance to address +Placing this module in Swift Numerics first gives the community a chance to address some of the compiler limitations that this feature ran into *before* it lands in the standard library (avoiding unnecessary source churn for projects that use these features), while also making it available *now*, including back-deployment to older Apple OS targets. diff --git a/Sources/ElementaryFunctions/ScalarConformances.swift b/Sources/ElementaryFunctions/ScalarConformances.swift index 621dc0b..02d9017 100644 --- a/Sources/ElementaryFunctions/ScalarConformances.swift +++ b/Sources/ElementaryFunctions/ScalarConformances.swift @@ -1,12 +1,11 @@ //===--- ScalarConformances.swift -----------------------------*- swift -*-===// // -// This source file is part of the Swift.org open source project +// This source file is part of the Swift Numerics open source project // -// Copyright (c) 2019 Apple Inc. and the Swift project authors +// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors // Licensed under Apache License v2.0 with Runtime Library Exception // // See https://swift.org/LICENSE.txt for license information -// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors // //===----------------------------------------------------------------------===// diff --git a/Sources/Numerics/Numerics.swift b/Sources/Numerics/Numerics.swift new file mode 100644 index 0000000..720613e --- /dev/null +++ b/Sources/Numerics/Numerics.swift @@ -0,0 +1,14 @@ +//===--- Numerics.swift ---------------------------------------*- swift -*-===// +// +// This source file is part of the Swift Numerics open source project +// +// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors +// Licensed under Apache License v2.0 with Runtime Library Exception +// +// See https://swift.org/LICENSE.txt for license information +// +//===----------------------------------------------------------------------===// + +// A module that re-exports the complete Swift Numerics public API. +@_exported import ElementaryFunctions +@_exported import Complex diff --git a/Sources/NumericsShims/NumericsShims.c b/Sources/NumericsShims/NumericsShims.c index 11583f7..4075174 100644 --- a/Sources/NumericsShims/NumericsShims.c +++ b/Sources/NumericsShims/NumericsShims.c @@ -1,12 +1,11 @@ //===--- NumericsShims.c --------------------------------------*- swift -*-===// // -// This source file is part of the Swift.org open source project +// This source file is part of the Swift Numerics open source project // -// Copyright (c) 2019 Apple Inc. and the Swift project authors +// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors // Licensed under Apache License v2.0 with Runtime Library Exception // // See https://swift.org/LICENSE.txt for license information -// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors // //===----------------------------------------------------------------------===// diff --git a/Sources/NumericsShims/include/NumericsShims.h b/Sources/NumericsShims/include/NumericsShims.h index 909123c..5824453 100644 --- a/Sources/NumericsShims/include/NumericsShims.h +++ b/Sources/NumericsShims/include/NumericsShims.h @@ -1,12 +1,11 @@ //===--- NumericsShims.h --------------------------------------*- swift -*-===// // -// This source file is part of the Swift.org open source project +// This source file is part of the Swift Numerics open source project // -// Copyright (c) 2019 Apple Inc. and the Swift project authors +// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors // Licensed under Apache License v2.0 with Runtime Library Exception // // See https://swift.org/LICENSE.txt for license information -// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors // //===----------------------------------------------------------------------===// diff --git a/Tests/ComplexTests/ComplexTests.swift b/Tests/ComplexTests/ComplexTests.swift index a4b936c..5ba0ef2 100644 --- a/Tests/ComplexTests/ComplexTests.swift +++ b/Tests/ComplexTests/ComplexTests.swift @@ -1,12 +1,11 @@ //===--- ComplexTests.swift -----------------------------------*- swift -*-===// // -// This source file is part of the Swift.org open source project +// This source file is part of the Swift Numerics open source project // -// Copyright (c) 2019 Apple Inc. and the Swift project authors +// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors // Licensed under Apache License v2.0 with Runtime Library Exception // // See https://swift.org/LICENSE.txt for license information -// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors // //===----------------------------------------------------------------------===// diff --git a/Tests/ElementaryFunctionTests/ElementaryFunctionTests.swift b/Tests/ElementaryFunctionTests/ElementaryFunctionTests.swift index 1023bba..ce753bb 100644 --- a/Tests/ElementaryFunctionTests/ElementaryFunctionTests.swift +++ b/Tests/ElementaryFunctionTests/ElementaryFunctionTests.swift @@ -1,12 +1,11 @@ //===--- ElementaryFunctionTests.swift ------------------------*- swift -*-===// // -// This source file is part of the Swift.org open source project +// This source file is part of the Swift Numerics open source project // -// Copyright (c) 2019 Apple Inc. and the Swift project authors +// Copyright (c) 2019 Apple Inc. and the Swift Numerics project authors // Licensed under Apache License v2.0 with Runtime Library Exception // // See https://swift.org/LICENSE.txt for license information -// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors // //===----------------------------------------------------------------------===//