pLIFE - the Game Of Life, advanced arithmetic engine
version 0.1


1. The licence
2. About
3. How to use
4. Warnings (please read this!)





-------------------
1. THE LICENCE

Copyright (C) 2008 by Bartosz Lenar
bartosz@lenar.org	
Licence: GNU LGPLv3

Some formal speech:
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License (version 3)
as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.





-------------------
2. ABOUT

The pLIFE is the engine for The Game Of Life (also called as Conway's Game Of Life). For more information, please check http://en.wikipedia.org/wiki/Conway%27s_Game_of_Life.

pLIFE counts the way that cells on the map should change. The advantage is, that pLIFE does not use array as the representation of the map. It means that it doesn't matter if your declared space is 20x20, or 10000000000x10000000000. pLIFE counts how many neighbors has each cell that has any chance to be changed and nothing more. Only the amount of actually living cells makes the difference in operation time.

Next advantage is, that pLIFE works according to custom rules. It is possible to play with standard Conway's rules 23/3, but you can specify, for example: 23458/15678, or whatever you want.




-------------------
3. HOW TO USE

First, you have to include pLIFE.h and vector...

	#include <vector>
	#include pLIFE.h

... and prepare some variables:

	int x = 20;
	int y = 20;

x and y are the measures of the map. I mentioned that the measures made no difference, but they have to be specified because pLIFE need to know when finally kill the cells. In the other case, the engine would be counting this to eternity.

	vector<int> startingCells;

This array contains the parameters of the cells that are alive at the beginning. If you would like to set cells: (2,3), (2,4), (3,3), you need to include this numbers to array. Simple example:

	startingCells.push_back(2);
	startingCells.push_back(3);

	startingCells.push_back(2);
	startingCells.push_back(4);

	startingCells.push_back(3);
	startingCells.push_back(3);

It's easy to observe that the first number in each pair is X parameter, and the second is Y.
Now, lets set up the rules. To use standard 23/3, do:

	vector<int> ruleAlive;
	ruleAlive.push_back(2);
	ruleAlive.push_back(3);
	vector<int> ruleCreate;
	ruleCreate.push_back(3);

For mentioned 23458/15678, just: 

	vector<int> ruleAlive;
	ruleAlive.push_back(2);
	ruleAlive.push_back(3);
	ruleAlive.push_back(4);
	ruleAlive.push_back(5);
	ruleAlive.push_back(8);
	vector<int> ruleCreate;
	ruleCreate.push_back(1);
	ruleCreate.push_back(5);
	ruleCreate.push_back(6);
	ruleCreate.push_back(7);
	ruleCreate.push_back(8);

The last thing before run is creating array where pLIFE will write changes on the map:

	vector<int> changes;

At least it's possible to use the engine:

	pLIFE exampleEngine(x,y,startingCells,ruleAlive,ruleCreate);

To make one step, just:

	exampleEngine.run(changes);

And the changes array now contains the parameters of the cells that has been changed. The format is the same as in startingCells. First of each pair of numbers is X, second- Y.

To do more than one step, type

	exampleEngine.run(changes,100);

The changes array will contain all differences between the previous state and the state 100 moves after.

Please study demo.cpp file for more practical examples of using pLIFE.



-------------------
4. WARNINGS

pLIFE doesn't check if data you initiate it with are correct.  So try not to give him pointless parameters etc. Because of the lack of time, I did not test such a situations.