simulation.dart 2.34 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter 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
import 'package:flutter/foundation.dart';

7
import 'tolerance.dart';
8

9 10
export 'tolerance.dart' show Tolerance;

Ian Hickson's avatar
Ian Hickson committed
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
/// The base class for all simulations.
///
/// A simulation models an object, in a one-dimensional space, on which particular
/// forces are being applied, and exposes:
///
///  * The object's position, [x]
///  * The object's velocity, [dx]
///  * Whether the simulation is "done", [isDone]
///
/// A simulation is generally "done" if the object has, to a given [tolerance],
/// come to a complete rest.
///
/// The [x], [dx], and [isDone] functions take a time argument which specifies
/// the time for which they are to be evaluated. In principle, simulations can
/// be stateless, and thus can be queried with arbitrary times. In practice,
/// however, some simulations are not, and calling any of these functions will
/// advance the simulation to the given time.
///
/// As a general rule, therefore, a simulation should only be queried using
/// times that are equal to or greater than all times previously used for that
/// simulation.
///
/// Simulations do not specify units for distance, velocity, and time. Client
/// should establish a convention and use that convention consistently with all
/// related objects.
36
abstract class Simulation {
37
  /// Initializes the [tolerance] field for subclasses.
38
  Simulation({ this.tolerance = Tolerance.defaultTolerance });
39

Ian Hickson's avatar
Ian Hickson committed
40
  /// The position of the object in the simulation at the given time.
41 42
  double x(double time);

Ian Hickson's avatar
Ian Hickson committed
43
  /// The velocity of the object in the simulation at the given time.
Ian Hickson's avatar
Ian Hickson committed
44
  double dx(double time);
45

Ian Hickson's avatar
Ian Hickson committed
46
  /// Whether the simulation is "done" at the given time.
47
  bool isDone(double time);
Ian Hickson's avatar
Ian Hickson committed
48 49 50 51 52 53 54 55

  /// How close to the actual end of the simulation a value at a particular time
  /// must be before [isDone] considers the simulation to be "done".
  ///
  /// A simulation with an asymptotic curve would never technically be "done",
  /// but once the difference from the value at a particular time and the
  /// asymptote itself could not be seen, it would be pointless to continue. The
  /// tolerance defines how to determine if the difference could not be seen.
56
  Tolerance tolerance;
57 58

  @override
59
  String toString() => objectRuntimeType(this, 'Simulation');
60
}