spring_simulation.dart 8.83 KB
Newer Older
1
// Copyright 2016 The Chromium Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5 6 7
import 'dart:math' as math;

import 'simulation.dart';
8
import 'tolerance.dart';
9 10
import 'utils.dart';

Ian Hickson's avatar
Ian Hickson committed
11 12 13 14
/// Structure that describes a spring's constants.
///
/// Used to configure a [SpringSimulation].
class SpringDescription {
15
  /// Creates a spring given the mass, stiffness, and the damping coefficient.
Ian Hickson's avatar
Ian Hickson committed
16
  ///
17
  /// See [mass], [stiffness], and [damping] for the units of the arguments.
Ian Hickson's avatar
Ian Hickson committed
18 19
  const SpringDescription({
    this.mass,
20
    this.stiffness,
Ian Hickson's avatar
Ian Hickson committed
21 22 23
    this.damping
  });

24
  /// Creates a spring given the mass (m), stiffness (k), and damping ratio (ζ).
25
  /// The damping ratio is especially useful trying to determining the type of
26 27
  /// spring to create. A ratio of 1.0 creates a critically damped spring, > 1.0
  /// creates an overdamped spring and < 1.0 an underdamped one.
Ian Hickson's avatar
Ian Hickson committed
28
  ///
29 30
  /// See [mass] and [stiffness] for the units for those arguments. The damping
  /// ratio is unitless.
Ian Hickson's avatar
Ian Hickson committed
31
  SpringDescription.withDampingRatio({
32
    this.mass,
33
    this.stiffness,
Ian Hickson's avatar
Ian Hickson committed
34
    double ratio: 1.0
35
  }) : damping = ratio * 2.0 * math.sqrt(mass * stiffness);
Ian Hickson's avatar
Ian Hickson committed
36 37 38 39 40

  /// The mass of the spring (m). The units are arbitrary, but all springs
  /// within a system should use the same mass units.
  final double mass;

41 42 43 44
  /// The spring constant (k). The units of stiffness are M/T², where M is the
  /// mass unit used for the value of the [mass] property, and T is the time
  /// unit used for driving the [SpringSimulation].
  final double stiffness;
Ian Hickson's avatar
Ian Hickson committed
45 46 47 48 49 50 51 52 53 54 55

  /// The damping coefficient (c).
  ///
  /// Do not confuse the damping _coefficient_ (c) with the damping _ratio_ (ζ).
  /// To create a [SpringDescription] with a damping ratio, use the [new
  /// SpringDescription.withDampingRatio] constructor.
  ///
  /// The units of the damping coefficient are M/T, where M is the mass unit
  /// used for the value of the [mass] property, and T is the time unit used for
  /// driving the [SpringSimulation].
  final double damping;
56 57

  @override
58
  String toString() => '$runtimeType(mass: ${mass.toStringAsFixed(1)}, stiffness: ${stiffness.toStringAsFixed(1)}, damping: ${damping.toStringAsFixed(1)})';
Ian Hickson's avatar
Ian Hickson committed
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
}

/// The kind of spring solution that the [SpringSimulation] is using to simulate the spring.
///
/// See [SpringSimulation.type].
enum SpringType {
  /// A spring that does not bounce and returns to its rest position in the
  /// shortest possible time.
  criticallyDamped,

  /// A spring that bounces.
  underDamped,

  /// A spring that does not bounce but takes longer to return to its rest
  /// position than a [criticallyDamped] one.
  overDamped,
}

/// A spring simulation.
///
/// Models a particle attached to a spring that follows Hooke's law.
class SpringSimulation extends Simulation {
  /// Creates a spring simulation from the provided spring description, start
  /// distance, end distance, and initial velocity.
  ///
  /// The units for the start and end distance arguments are arbitrary, but must
  /// be consistent with the units used for other lengths in the system.
  ///
  /// The units for the velocity are L/T, where L is the aforementioned
  /// arbitrary unit of length, and T is the time unit used for driving the
  /// [SpringSimulation].
  SpringSimulation(
91
    SpringDescription spring,
Ian Hickson's avatar
Ian Hickson committed
92 93
    double start,
    double end,
94 95 96 97 98
    double velocity, {
    Tolerance tolerance: Tolerance.defaultTolerance,
  }) : _endPosition = end,
      _solution = new _SpringSolution(spring, start - end, velocity),
      super(tolerance: tolerance);
Ian Hickson's avatar
Ian Hickson committed
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119

  final double _endPosition;
  final _SpringSolution _solution;

  /// The kind of spring being simulated, for debugging purposes.
  ///
  /// This is derived from the [SpringDescription] provided to the [new
  /// SpringSimulation] constructor.
  SpringType get type => _solution.type;

  @override
  double x(double time) => _endPosition + _solution.x(time);

  @override
  double dx(double time) => _solution.dx(time);

  @override
  bool isDone(double time) {
    return nearZero(_solution.x(time), tolerance.distance) &&
           nearZero(_solution.dx(time), tolerance.velocity);
  }
120 121 122

  @override
  String toString() => '$runtimeType(end: $_endPosition, $type)';
Ian Hickson's avatar
Ian Hickson committed
123 124 125 126 127 128 129 130 131 132 133
}

/// A SpringSimulation where the value of [x] is guaranteed to have exactly the
/// end value when the simulation isDone().
class ScrollSpringSimulation extends SpringSimulation {
  /// Creates a spring simulation from the provided spring description, start
  /// distance, end distance, and initial velocity.
  ///
  /// See the [new SpringSimulation] constructor on the superclass for a
  /// discussion of the arguments' units.
  ScrollSpringSimulation(
134
    SpringDescription spring,
Ian Hickson's avatar
Ian Hickson committed
135 136
    double start,
    double end,
137 138 139
    double velocity, {
    Tolerance tolerance: Tolerance.defaultTolerance,
  }) : super(spring, start, end, velocity, tolerance: tolerance);
Ian Hickson's avatar
Ian Hickson committed
140 141 142 143 144 145 146

  @override
  double x(double time) => isDone(time) ? _endPosition : super.x(time);
}


// SPRING IMPLEMENTATIONS
147

148 149
abstract class _SpringSolution {
  factory _SpringSolution(
150
    SpringDescription spring,
151 152 153
    double initialPosition,
    double initialVelocity
  ) {
154 155
    assert(spring != null);
    assert(spring.mass != null);
156
    assert(spring.stiffness != null);
157
    assert(spring.damping != null);
Ian Hickson's avatar
Ian Hickson committed
158 159
    assert(initialPosition != null);
    assert(initialVelocity != null);
160
    final double cmk = spring.damping * spring.damping - 4 * spring.mass * spring.stiffness;
161
    if (cmk == 0.0)
162
      return new _CriticalSolution(spring, initialPosition, initialVelocity);
163
    if (cmk > 0.0)
164 165
      return new _OverdampedSolution(spring, initialPosition, initialVelocity);
    return new _UnderdampedSolution(spring, initialPosition, initialVelocity);
166 167
  }

168 169
  double x(double time);
  double dx(double time);
170 171 172 173 174
  SpringType get type;
}

class _CriticalSolution implements _SpringSolution {
  factory _CriticalSolution(
175
    SpringDescription spring,
176 177 178
    double distance,
    double velocity
  ) {
179
    final double r = -spring.damping / (2.0 * spring.mass);
180 181 182 183 184 185
    final double c1 = distance;
    final double c2 = velocity / (r * distance);
    return new _CriticalSolution.withArgs(r, c1, c2);
  }

  _CriticalSolution.withArgs(double r, double c1, double c2)
186 187 188
    : _r = r,
      _c1 = c1,
      _c2 = c2;
189

190 191
  final double _r, _c1, _c2;

192
  @override
193 194 195
  double x(double time) {
    return (_c1 + _c2 * time) * math.pow(math.E, _r * time);
  }
196

197
  @override
198 199 200 201
  double dx(double time) {
    final double power = math.pow(math.E, _r * time);
    return _r * (_c1 + _c2 * time) * power + _c2 * power;
  }
202

203
  @override
204
  SpringType get type => SpringType.criticallyDamped;
205 206 207 208
}

class _OverdampedSolution implements _SpringSolution {
  factory _OverdampedSolution(
209
    SpringDescription spring,
210 211 212
    double distance,
    double velocity
  ) {
213
    final double cmk = spring.damping * spring.damping - 4 * spring.mass * spring.stiffness;
214 215
    final double r1 = (-spring.damping - math.sqrt(cmk)) / (2.0 * spring.mass);
    final double r2 = (-spring.damping + math.sqrt(cmk)) / (2.0 * spring.mass);
216 217 218 219 220 221
    final double c2 = (velocity - r1 * distance) / (r2 - r1);
    final double c1 = distance - c2;
    return new _OverdampedSolution.withArgs(r1, r2, c1, c2);
  }

  _OverdampedSolution.withArgs(double r1, double r2, double c1, double c2)
222 223 224 225
    : _r1 = r1,
      _r2 = r2,
      _c1 = c1,
      _c2 = c2;
226

227
  final double _r1, _r2, _c1, _c2;
228

229
  @override
230 231 232 233 234
  double x(double time) {
    return _c1 * math.pow(math.E, _r1 * time) +
           _c2 * math.pow(math.E, _r2 * time);
  }

235
  @override
236 237 238 239
  double dx(double time) {
    return _c1 * _r1 * math.pow(math.E, _r1 * time) +
           _c2 * _r2 * math.pow(math.E, _r2 * time);
  }
240

241
  @override
242
  SpringType get type => SpringType.overDamped;
243 244 245 246
}

class _UnderdampedSolution implements _SpringSolution {
  factory _UnderdampedSolution(
247
    SpringDescription spring,
248 249 250
    double distance,
    double velocity
  ) {
251
    final double w = math.sqrt(4.0 * spring.mass * spring.stiffness -
252 253
                     spring.damping * spring.damping) / (2.0 * spring.mass);
    final double r = -(spring.damping / 2.0 * spring.mass);
254 255 256 257 258 259
    final double c1 = distance;
    final double c2 = (velocity - r * distance) / w;
    return new _UnderdampedSolution.withArgs(w, r, c1, c2);
  }

  _UnderdampedSolution.withArgs(double w, double r, double c1, double c2)
260 261 262 263
    : _w = w,
      _r = r,
      _c1 = c1,
      _c2 = c2;
264

265
  final double _w, _r, _c1, _c2;
266

267
  @override
268 269 270 271
  double x(double time) {
    return math.pow(math.E, _r * time) *
           (_c1 * math.cos(_w * time) + _c2 * math.sin(_w * time));
  }
272

273
  @override
274 275 276 277
  double dx(double time) {
    final double power = math.pow(math.E, _r * time);
    final double cosine = math.cos(_w * time);
    final double sine = math.sin(_w * time);
278 279
    return      power * (_c2 * _w * cosine - _c1 * _w * sine) +
           _r * power * (_c2 *      sine   + _c1 *      cosine);
280
  }
281

282
  @override
283
  SpringType get type => SpringType.underDamped;
284
}