[AutoDiff] Rename 'move(along:)' to 'move(by:)'.

Rename `move(along:)` to `move(by:)` based on the proposal feedback. The main argument for the change is that tangent vectors specify both a direction and a magnitude, whereas `along:` does not indicate that `self` is being moved by the specified magnitude.

Author: rxwei

docs/DifferentiableProgramming.md

@@ -982,10 +982,10 @@ public protocol Differentiable {
     associatedtype TangentVector: Differentiable & AdditiveArithmetic
         where TangentVector == TangentVector.TangentVector
 
-    /// Moves `self` along the given direction. In Riemannian geometry, this is
+    /// Moves `self` by the given offset. In Riemannian geometry, this is
     /// equivalent to exponential map, which moves `self` on the geodesic
-    /// surface along the given tangent vector.
-    mutating func move(along direction: TangentVector)
+    /// surface by the given tangent vector.
+    mutating func move(by offset: TangentVector)
 }
 ```
 
@@ -1037,19 +1037,19 @@ and
 [`+(_:_:)`](https://developer.apple.com/documentation/swift/additivearithmetic/3126821)
 are necessary for initializing and accumulating derivative values.
 
-The `move(along:)` method is equivalent to the mathematical notion of
+The `move(by:)` method is equivalent to the mathematical notion of
 [exponential map](https://en.wikipedia.org/wiki/Exponential_map_\(Riemannian_geometry\)),
 which takes a tangent vector (e.g. a derivative), and moves the value along the
 direction specified by the tangent vector on the geodesic surface of the
 manifold. In vector spaces where the tangent vector is of the same vector space
-as the original differentiable space, `move(along:)` is equivalent to vector
+as the original differentiable space, `move(by:)` is equivalent to vector
 addition. Mathematical optimization algorithms such as gradient descent will
 make use of this method.
 
 ```swift
 public extension Differentiable where Self == TangentVector {
-    mutating func move(along direction: TangentVector) {
-        self += direction
+    mutating func move(by offset: TangentVector) {
+        self += offset
     }
 }
 ```
@@ -1096,9 +1096,9 @@ extension Array: Differentiable where Element: Differentiable {
         ...
     }
 
-    public mutating func move(along direction: TangentVector) {
+    public mutating func move(by offset: TangentVector) {
         for i in indices {
-            self[i].move(along: Element.TangentVector(direction.elements[i]))
+            self[i].move(by: Element.TangentVector(offset.elements[i]))
         }
     }
 }
@@ -1116,9 +1116,9 @@ extension Dictionary: Differentiable where Value: Differentiable {
         ...
     }
 
-    public mutating func move(along direction: TangentVector) {
+    public mutating func move(by offset: TangentVector) {
         for i in indices {
-            self[i].move(along: Value.TangentVector(direction.elements[i]))
+            self[i].move(by: Value.TangentVector(offset.elements[i]))
         }
     }
 }
@@ -1134,9 +1134,9 @@ extension Optional: Differentiable where Wrapped: Differentiable {
         ...
     }
 
-    public mutating func move(along direction: TangentVector) {
-        if let value = direction.value {
-            self?.move(along: value)
+    public mutating func move(by offset: TangentVector) {
+        if let value = offset.value {
+            self?.move(by: value)
         }
     }
 }
@@ -1189,12 +1189,12 @@ product manifold of the manifolds each differentiable variable's type
 represents. Differentiable variables' types are required to conform to
 `Differentiable` because the synthesized implementation needs to access each
 differentiable variable's type's `TangentVector` associated type and invoke each
-differentiable variable's implementation of `move(along:)`. Because the
-synthesized implementation needs to invoke `move(along:)` on each differentiable
-variable, the differentiable variables must have a `move(along:)` which satisfies the
+differentiable variable's implementation of `move(by:)`. Because the
+synthesized implementation needs to invoke `move(by:)` on each differentiable
+variable, the differentiable variables must have a `move(by:)` which satisfies the
 protocol requirement and can be invoked on the property. That is, the property
 must be either a variable (`var`) or a constant (`let`) with a non-`mutating`
-implementation of the `move(along:)` protocol requirement.
+implementation of the `move(by:)` protocol requirement.
 
 The synthesized `TangentVector` has the same effective access level as the
 original type declaration. Properties in the synthesized `TangentVector` have
@@ -1206,7 +1206,7 @@ example, synthesized `TangentVector`s always adopt the `AdditiveArithmetic` and
 `Differentiable` protocols because the `Differentiable` protocol requires that
 `TangentVector` conforms to `AdditiveArithmetic` and `Differentiable`.
 
-The synthesized `move(along:)` method calls `move(along:)` for each pair of a
+The synthesized `move(by:)` method calls `move(by:)` for each pair of a
 differentiable variable and its corresponding property in `TangentVector`.
 
 ```swift
@@ -1223,9 +1223,9 @@ struct Foo<T: Differentiable, U: Differentiable>: @memberwise Differentiable {
     //         var y: U.TangentVector
     //     }
     //
-    //     mutating func move(along direction: TangentVector) {
-    //         x.move(along: direction.x)
-    //         y.move(along: direction.y)
+    //     mutating func move(by offset: TangentVector) {
+    //         x.move(by: offset.x)
+    //         y.move(by: offset.y)
     //     }
 }
 ```
@@ -1235,7 +1235,7 @@ struct Foo<T: Differentiable, U: Differentiable>: @memberwise Differentiable {
 The synthesized implementation of `Differentiable` protocol requirements already
 excludes stored properties that are not differentiable variables, such as stored
 properties that do not conform to `Differentiable` and `let`
-properties that do not have a non-mutating `move(along:)`. In addition to this
+properties that do not have a non-mutating `move(by:)`. In addition to this
 behavior, we also introduce a `@noDerivative` declaration attribute, which can
 be attached to properties that the programmer does not wish to include in the
 synthesized `Differentiable` protocol requirement implementation.
@@ -1284,7 +1284,7 @@ test.swift:5:4: note: add a '@noDerivative' attribute to make it explicit
     ^
     @noDerivative
 
-test.swift:6:4: warning: synthesis of the 'Differentiable.move(along:)' requirement for 'Foo' requires all stored properties not marked with `@noDerivative` to be mutable
+test.swift:6:4: warning: synthesis of the 'Differentiable.move(by:)' requirement for 'Foo' requires all stored properties not marked with `@noDerivative` to be mutable
     let helperVariable: T
 
 test.swift:6:4: note: change 'let' to 'var' to make it mutable
@@ -1307,7 +1307,7 @@ properties are declared to conform to `AdditiveArithmetic`. There are no
 `@noDerivative` stored properties.
 
 In these cases, the compiler will make `TangentVector` be a type alias for Self.
-Method `move(along:)` will not be synthesized because a default implementation
+Method `move(by:)` will not be synthesized because a default implementation
 already exists.
 
 ```swift
@@ -2743,7 +2743,7 @@ for i in 0..<iterationCount {
     }
     𝛁loss.weight *= -learningRate
     𝛁loss.bias *= -learningRate
-    model.move(along: 𝛁loss)
+    model.move(by: 𝛁loss)
     if i.isMultiple(of: 10) {
         print("Iteration: \(iteration) Avg Loss: \(loss / Float(data.count))")
     }

include/swift/AST/DiagnosticsSema.def

@@ -2869,16 +2869,16 @@ WARNING(differentiable_nondiff_type_implicit_noderivative_fixit,none,
       (/*propName*/ Identifier, /*propType*/ Type, /*nominalName*/ Identifier,
        /*nominalCanDeriveAdditiveArithmetic*/ bool))
 WARNING(differentiable_immutable_wrapper_implicit_noderivative_fixit,none,
-      "synthesis of the 'Differentiable.move(along:)' requirement for %1 "
+      "synthesis of the 'Differentiable.move(by:)' requirement for %1 "
       "requires 'wrappedValue' in property wrapper %0 to be mutable or have a "
-      "non-mutating 'move(along:)'; add an explicit '@noDerivative' attribute"
+      "non-mutating 'move(by:)'; add an explicit '@noDerivative' attribute"
       "%select{|, or conform %1 to 'AdditiveArithmetic'}2",
       (/*wrapperType*/ Identifier, /*nominalName*/ Identifier,
        /*nominalCanDeriveAdditiveArithmetic*/ bool))
 WARNING(differentiable_let_property_implicit_noderivative_fixit,none,
-      "synthesis of the 'Differentiable.move(along:)' requirement for %0 "
+      "synthesis of the 'Differentiable.move(by:)' requirement for %0 "
       "requires all stored properties not marked with `@noDerivative` to be "
-      "mutable or have a non-mutating 'move(along:)'; use 'var' instead, or "
+      "mutable or have a non-mutating 'move(by:)'; use 'var' instead, or "
       "add an explicit '@noDerivative' attribute "
       "%select{|, or conform %0 to 'AdditiveArithmetic'}1",
       (/*nominalName*/ Identifier, /*nominalCanDeriveAdditiveArithmetic*/ bool))

include/swift/AST/KnownIdentifiers.def

@@ -228,9 +228,9 @@ IDENTIFIER(AtomicStoreOrdering)
 IDENTIFIER(AtomicUpdateOrdering)
 
 // Differentiable programming
-IDENTIFIER(along)
+IDENTIFIER(by)
 IDENTIFIER(differential)
-IDENTIFIER(direction)
+IDENTIFIER(offset)
 IDENTIFIER(move)
 IDENTIFIER(pullback)
 IDENTIFIER(TangentVector)

lib/Sema/DerivedConformanceDifferentiable.cpp

@@ -34,24 +34,24 @@
 
 using namespace swift;
 
-/// Return true if `move(along:)` can be invoked on the given `Differentiable`-
+/// Return true if `move(by:)` can be invoked on the given `Differentiable`-
 /// conforming property.
 ///
-/// If the given property is a `var`, return true because `move(along:)` can be
+/// If the given property is a `var`, return true because `move(by:)` can be
 /// invoked regardless.  Otherwise, return true if and only if the property's
-/// type's 'Differentiable.move(along:)' witness is non-mutating.
+/// type's 'Differentiable.move(by:)' witness is non-mutating.
 static bool canInvokeMoveAlongOnProperty(
     VarDecl *vd, ProtocolConformanceRef diffableConformance) {
   assert(diffableConformance && "Property must conform to 'Differentiable'");
-  // `var` always supports `move(along:)` since it is mutable.
+  // `var` always supports `move(by:)` since it is mutable.
   if (vd->getIntroducer() == VarDecl::Introducer::Var)
     return true;
   // When the property is a `let`, the only case that would be supported is when
-  // it has a `move(along:)` protocol requirement witness that is non-mutating.
+  // it has a `move(by:)` protocol requirement witness that is non-mutating.
   auto interfaceType = vd->getInterfaceType();
   auto &C = vd->getASTContext();
   auto witness = diffableConformance.getWitnessByName(
-      interfaceType, DeclName(C, C.Id_move, {C.Id_along}));
+      interfaceType, DeclName(C, C.Id_move, {C.Id_by}));
   if (!witness)
     return false;
   auto *decl = cast<FuncDecl>(witness.getDecl());
@@ -70,7 +70,7 @@ getStoredPropertiesForDifferentiation(
   for (auto *vd : nominal->getStoredProperties()) {
     // Peer through property wrappers: use original wrapped properties instead.
     if (auto *originalProperty = vd->getOriginalWrappedProperty()) {
-      // Skip immutable wrapped properties. `mutating func move(along:)` cannot
+      // Skip immutable wrapped properties. `mutating func move(by:)` cannot
       // be synthesized to update these properties.
       if (!originalProperty->isSettable(DC))
         continue;
@@ -87,8 +87,8 @@ getStoredPropertiesForDifferentiation(
         varType, diffableProto, nominal);
     if (!conformance)
       continue;
-    // Skip `let` stored properties with a mutating `move(along:)` if requested.
-    // `mutating func move(along:)` cannot be synthesized to update `let`
+    // Skip `let` stored properties with a mutating `move(by:)` if requested.
+    // `mutating func move(by:)` cannot be synthesized to update `let`
     // properties.
     if (!includeLetPropertiesWithNonmutatingMoveAlong && 
         !canInvokeMoveAlongOnProperty(vd, conformance))
@@ -214,14 +214,14 @@ bool DerivedConformance::canDeriveDifferentiable(NominalTypeDecl *nominal,
   });
 }
 
-/// Synthesize body for `move(along:)`.
+/// Synthesize body for `move(by:)`.
 static std::pair<BraceStmt *, bool>
 deriveBodyDifferentiable_move(AbstractFunctionDecl *funcDecl, void *) {
   auto &C = funcDecl->getASTContext();
   auto *parentDC = funcDecl->getParent();
   auto *nominal = parentDC->getSelfNominalTypeDecl();
 
-  // Get `Differentiable.move(along:)` protocol requirement.
+  // Get `Differentiable.move(by:)` protocol requirement.
   auto *diffProto = C.getProtocol(KnownProtocolKind::Differentiable);
   auto *requirement = getProtocolRequirement(diffProto, C.Id_move);
 
@@ -236,31 +236,31 @@ deriveBodyDifferentiable_move(AbstractFunctionDecl *funcDecl, void *) {
   SmallVector<VarDecl *, 8> diffProperties;
   getStoredPropertiesForDifferentiation(nominal, parentDC, diffProperties);
 
-  // Create call expression applying a member `move(along:)` method to a
-  // parameter member: `self.<member>.move(along: direction.<member>)`.
+  // Create call expression applying a member `move(by:)` method to a
+  // parameter member: `self.<member>.move(by: offset.<member>)`.
   auto createMemberMethodCallExpr = [&](VarDecl *member) -> Expr * {
     auto *module = nominal->getModuleContext();
     auto memberType =
         parentDC->mapTypeIntoContext(member->getValueInterfaceType());
     auto confRef = module->lookupConformance(memberType, diffProto);
     assert(confRef && "Member does not conform to `Differentiable`");
 
-    // Get member type's requirement witness: `<Member>.move(along:)`.
+    // Get member type's requirement witness: `<Member>.move(by:)`.
     ValueDecl *memberWitnessDecl = requirement;
     if (confRef.isConcrete())
       if (auto *witness = confRef.getConcrete()->getWitnessDecl(requirement))
         memberWitnessDecl = witness;
     assert(memberWitnessDecl && "Member witness declaration must exist");
 
-    // Create reference to member method: `self.<member>.move(along:)`.
+    // Create reference to member method: `self.<member>.move(by:)`.
     Expr *memberExpr =
         new (C) MemberRefExpr(selfDRE, SourceLoc(), member, DeclNameLoc(),
                               /*Implicit*/ true);
     auto *memberMethodExpr =
         new (C) MemberRefExpr(memberExpr, SourceLoc(), memberWitnessDecl,
                               DeclNameLoc(), /*Implicit*/ true);
 
-    // Create reference to parameter member: `direction.<member>`.
+    // Create reference to parameter member: `offset.<member>`.
     VarDecl *paramMember = nullptr;
     auto *paramNominal = paramDecl->getType()->getAnyNominal();
     assert(paramNominal && "Parameter should have a nominal type");
@@ -275,12 +275,12 @@ deriveBodyDifferentiable_move(AbstractFunctionDecl *funcDecl, void *) {
     auto *paramMemberExpr =
         new (C) MemberRefExpr(paramDRE, SourceLoc(), paramMember, DeclNameLoc(),
                               /*Implicit*/ true);
-    // Create expression: `self.<member>.move(along: direction.<member>)`.
+    // Create expression: `self.<member>.move(by: offset.<member>)`.
     return CallExpr::createImplicit(C, memberMethodExpr, {paramMemberExpr},
-                                    {C.Id_along});
+                                    {C.Id_by});
   };
 
-  // Collect member `move(along:)` method call expressions.
+  // Collect member `move(by:)` method call expressions.
   SmallVector<ASTNode, 2> memberMethodCallExprs;
   SmallVector<Identifier, 2> memberNames;
   for (auto *member : diffProperties) {
@@ -326,14 +326,14 @@ static ValueDecl *deriveDifferentiable_method(
   return funcDecl;
 }
 
-/// Synthesize the `move(along:)` function declaration.
+/// Synthesize the `move(by:)` function declaration.
 static ValueDecl *deriveDifferentiable_move(DerivedConformance &derived) {
   auto &C = derived.Context;
   auto *parentDC = derived.getConformanceContext();
   auto tangentType =
       getTangentVectorInterfaceType(parentDC->getSelfTypeInContext(), parentDC);
   return deriveDifferentiable_method(
-      derived, C.Id_move, C.Id_along, C.Id_direction, tangentType,
+      derived, C.Id_move, C.Id_by, C.Id_offset, tangentType,
       C.TheEmptyTupleType, {deriveBodyDifferentiable_move, nullptr});
 }
 
@@ -561,7 +561,7 @@ static void checkAndDiagnoseImplicitNoDerivative(ASTContext &Context,
       if (originalProperty->getAttrs().hasAttribute<NoDerivativeAttr>())
         continue;
       // Diagnose wrapped properties whose property wrappers do not define
-      // `wrappedValue.set`. `mutating func move(along:)` cannot be synthesized
+      // `wrappedValue.set`. `mutating func move(by:)` cannot be synthesized
       // to update these properties.
       if (!originalProperty->isSettable(DC)) {
         auto *wrapperDecl =

lib/Sema/DerivedConformances.cpp

@@ -329,10 +329,10 @@ ValueDecl *DerivedConformance::getDerivableRequirement(NominalTypeDecl *nominal,
       return getRequirement(KnownProtocolKind::AdditiveArithmetic);
     }
 
-    // Differentiable.move(along:)
+    // Differentiable.move(by:)
     if (name.isCompoundName() && name.getBaseName() == ctx.Id_move) {
       auto argumentNames = name.getArgumentNames();
-      if (argumentNames.size() == 1 && argumentNames[0] == ctx.Id_along)
+      if (argumentNames.size() == 1 && argumentNames[0] == ctx.Id_by)
         return getRequirement(KnownProtocolKind::Differentiable);
     }