-----------------------------------------------------------------------------
-- Particle Simulation Toolkit ----------------------------------------------
-- 2003-01-20 ---------------------------------------------------------------
-----------------------------------------------------------------------------

The Particle Simulation Toolkit was designed to fulfil a multitude of 
slightly differing kinds of particle simulation, by simply exchanging or 
rewriting a few classes. Thus, the whole class design may firstly appear 
puzzling to the the untaught programmer. But, in fact, closer look may reveal
some system in the apparent chaos.

The pivot of all our simulation is the SPhaseSpace class. It contains all the
system's non-dynamic information, such as density, particle count, positions,
velocities, masses, ..., and some methods for manipulating them.
A lot of classes is derived from SModule, they are specialized in working with
and/or on the particles. The whole dynamics of the simulation, for example,
is managed by one ore more modules. Paircorrelation calculation is stored in
a module, and so on. [.. to be continued ..]

Well, let's try to illustrate all by a little example:

-----------------------------------------------------------------------------
-- EXAMPLE ------------------------------------------------------------------
-----------------------------------------------------------------------------

// in the beginning there was a box... full of particles
PhaseSpace = new SPhaseSpace(DIMENSION, PARTICLES);
	
// then we decided they should have lennard jones-interaction
Interaction = new SLJInteraction;
	
// we need a procedure to calculate distances...
DistanceMatrix = new SDistanceMatrix(PhaseSpace, false);
	
// and something that integrates the particle's equations of motion
Integrator = new SimCoreMD(TIMESTEP, PhaseSpace, Interaction, DistanceMatrix);
	
// we need to give the particles values to start with ...
InitCrystal = new SInitCrystal(PhaseSpace);
	
// ... functions to survey the order in our box ...
MeltingFactor = new SMeltingFactor(PhaseSpace);
	
// ... to measure and influence temperature ...
KineticEnergy = new SKineticEnergy(PhaseSpace);
Thermostate = new SThermostate(PhaseSpace, KineticEnergy);

// ... and bring chaos to initial states of order.	
Meltdown = new SMeltdown(PhaseSpace, Integrator, MeltingFactor, Thermostate, TEMPERATURE);

// well, we begin by placing our little particles on a fcc lattice
InitCrystal->Execute();
	
// and tell the integrator it shall set her mind up
Integrator->Initialize();

// since we would like to simulate a fluid, we'll have to melt the crystal down
// (and compress it to densities we like)
Meltdown->Execute(DENSITY, true);

// now it's time to make some real simulating... but we'd like to see some results, don't we?

// pair correlation functions ...
PCF = new SDBPairCorrFunc(PhaseSpace, DistanceMatrix->Distances);
PCF->Initialize();

// ... and velocity autocorrelation should be enough for the beginning
ACFV = new SAutoCorrelV(PhaseSpace, TIMESTEP);
ACFV->Initialize();

// we've written a cute class for output to files and console!
SOutput Output(&cout);
Output.Initialize();

// it's also cool to know about parameters and so on, so we note them down
Output.AddParam("Dimension", DIMENSION);
Output.AddParam("Particles", PARTICLES);
Output.AddParam("Packing Density", DENSITY);
Output.AddParam("Temperature", TEMPERATURE);
Output.AddParam("Timestep", TIMESTEP);
Output.AddParam("Iterations", ITERATIONS);
Output.Header("Lennard Jones Dumbbell Molecules");

// NOW we're ready to start!

// we iterate a few times
for (int i=0; i<ITERATIONS; i++)
{
	// the integrator shall execute one single step, and calculating velocities, too
	Integrator->Execute(1, true);
	
	// we note down all the stuff the velocity autocorrelation needs...
	ACFV->Execute();
	
	// and every some 50 steps what the pair correlation function wants to know
	if (i%PCFSTEP==0) PCF->Execute();
}

// now that the simulation is over, we consider normalizing and saving the results
// the diagram's data is written to a file using Output's header information!
PCF->Finalize();
PCF->Output(&Output);
ACFV->Output(&Output);
	
-----------------------------------------------------------------------------
-- e.o.e(xample) ------------------------------------------------------------
-----------------------------------------------------------------------------