simulation.dart 2.24 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
import 'tolerance.dart';
6

Ian Hickson's avatar
Ian Hickson committed
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
/// 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.
32
abstract class Simulation {
33
  /// Initializes the [tolerance] field for subclasses.
34 35
  Simulation({ this.tolerance: Tolerance.defaultTolerance });

Ian Hickson's avatar
Ian Hickson committed
36
  /// The position of the object in the simulation at the given time.
37 38
  double x(double time);

Ian Hickson's avatar
Ian Hickson committed
39
  /// The velocity of the object in the simulation at the given time.
Ian Hickson's avatar
Ian Hickson committed
40
  double dx(double time);
41

Ian Hickson's avatar
Ian Hickson committed
42
  /// Whether the simulation is "done" at the given time.
43
  bool isDone(double time);
Ian Hickson's avatar
Ian Hickson committed
44 45 46 47 48 49 50 51

  /// 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.
52
  Tolerance tolerance;
53 54 55

  @override
  String toString() => '$runtimeType';
56
}