# NAME

App::Physics::ParticleMotion - Simulations from Differential Equations

# SYNOPSIS

```
# You can use the tk-motion.pl script instead.
use App::Physics::ParticleMotion;
my $app = App::Physics::ParticleMotion->new();
$app->config('filename'); # Or pass a Config::Tiny object instead
$app->run();
# Using the script:
# tk-motion.pl filename
```

# DESCRIPTION

tk-motion (and its implementation App::Physics::ParticleMotion) is a tool to create particle simulations from any number of correlated second order differential equations. From a more mathematical point of view, one could also say it helps visualize the numeric solution of such differential equations.

The program uses a 4th-order Runge-Kutta integrator to find the numeric solution of the specified differential equations. We will walk through an example configuration file step by step to show how the process works. The format of the configuration files is the ordinary ini file format as understood by Config::Tiny. (Should be self explanatory.)

# EXAMPLES

## Long Example

The following **extensive** example comes with the distribution as "ex1.ini". See below for a minimal working example.

```
# This will be a one-dimensional harmonic oszillator (in 2D-space)
# Number of dimensions in simulation (up to three dimensions allowed)
dimensions = 2
# Given a sufficiently fast cpu, you can have the simulation run very fast
# by setting this to a high value. Setting it to one makes the simualtion
# pause after integration steps so that the total speed is no greater
# than realtime.
timewarp = 1
# The sensitivity of the integrator.
# Smaller is more accurate but more cpu intensive.
epsilon = 0.0000001
# Set to a true value to have the particle traces stay on screen.
# Note, however, that this tends to increase memory usage with time - slowly.
# This option may be omitted and defaults to false.
trace = 0
# Set this to any HTML color to change the axis' color.
# This option may be omitted and defaults to black.
axiscolor = #222277
# This sets the zoom. It may be omitted and defaults to 20 for
# backwards compatibility.
zoom = 60
# The following options specify the base point and the plane vectors
# for the viewing plane. (That's the plane you project the 3D coordinates on.)
# Make sure your vectors are normalized because otherwise your display will
# be stretched.
# The values in this example are at the same time the default values.
plane_base_x = 0
plane_base_y = 0
plane_base_z = 0
plane_vec1_x = 0.371391
plane_vec1_y = 0.928477
plane_vec1_z = 0
plane_vec2_x = 0.371391
plane_vec2_y = 0
plane_vec2_z = 0.928477
# You may omit this option. If you don't, however, all 3D data will be written
# to the specified file for further processing. (For example with
# tk-motion-img.pl.)
# output_file = ex1.dat
# This section contains any number of constants that may be used in the
# formulas that define the differential equations. The section should
# exist, but it may be empty.
[constants]
k = 1
m = 1
# This section defines the movement of the first particle (p1).
[p1]
# This is the differential equation of the first coordinate of the
# first particle. It is of the form
# (d^2/dt^2) x1 = yourformula
# "yourformula" may be any string that is correctly parsed by the
# Math::Symbolic parser. It may contain the constants specified above
# and any of the following variables:
# x1 is the first (hence "x") coordinate of the first particle (hence "x1").
# x2 is the x-coordinate of the second particle if it exists, and so on.
# y3 therefore represents the second coordinate of the third particle whereas
# z8 is the third coordinate of the eigth particle.
# Note that this example simulation only has two dimensions and hence
# "z8" doesn't exist.
# vx1 is the x-component of the velocity of the first particle.
# Therefore, vy3 represents the y-component of the velocity of the
# third particle. You get the general idea...
# All formulas may be correlated with other differential equations.
# That means, "funcx" of the first particle may contain y2 and the
# like. (Provided the dimensions and the particles exist.)
#
# Our example is a simple oszillator
funcx = - k/m * x1*(x1^2)^0.5
# Diff. eq. for the second coordinate of the first particle
# We want a 1-dimensional oszillator, so we set this to zero.
funcy = 0
# Initial values for the coordinates and velocity of the first particle.
x = 0
y = -0.5
vx = -20
vy = 0
# Color of the current location of the particle (default: white)
# HTML-style colors.
color = #FF0000
# Color of the particle's trace if trace == 1 (default: black)
colort = #880000
# Other particles are defined in the same fashion.
```

## Short Example

This example pretty much reproduces the extensive example above omitting any options that aren't mandatory (or required to make the examples the same).

```
# This will be a one-dimensional harmonic oszillator (in 2D-space)
dimensions = 2
zoom = 60
[constants]
k = 1
m = 1
[p1]
funcx = - k/m * x1*(x1^2)^0.5
funcy = 0
x = 0
y = -0.5
vx = -20
vy = 0
```

# METHODS

## new

Returns a new App::Physics::ParticleMotion object.

## config

Returns the current configuration as a Config::Tiny object. If a first argument is passed, it is used as the new configuration. It may be either a Config::Tiny object to replace the old one or the name of a file to read from.

## run

Runs the application. Can't be called more than once.

# SEE ALSO

New versions of this module can be found on http://steffen-mueller.net or CPAN.

Math::Symbolic implements the formula parser, compiler and evaluator. (See also Math::Symbolic::Parser and Math::Symbolic::Compiler.)

Config::Tiny implements the configuration reader.

Tk in conjunction with Tk::Cloth offer the GUI.

Math::RungeKutta implements the integrator.

Math::Project3D projects the 3D data onto a viewing plane.

# AUTHOR

Steffen Mueller, <particles-module at steffen-mueller dot net<gt>

# COPYRIGHT AND LICENSE

Copyright (C) 2004-2005 by Steffen Mueller

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.1 or, at your option, any later version of Perl 5 you may have available.