added a lot of stuff and formatting

README.md

@@ -1,48 +1,71 @@
-# AIrium 2
+# newAIrium description paper
 
-AIrium is an artificial life simulation environment. The second iteration of the project
+AIrium is an effort to create a working, complex artificial life simulation environment.
-focuses on solving the problems of the first:
+
+### Description
+
+This new iteration of the project focuses on solving the problems of the first:
 
 - variety in creature body and mind structure
 - removing evolution limits (such as brain size)
 - allowing different species to mate and produce possibly stable children
 - speed: trying to get the simulation to be as fast as possible on consumer grade hardware
+- documentation: having an actual model to follow
+- concurrency: try to enable the maximum concurrency when simulating the world, to the point that multiple
+  networked computers may collaborate and work together to simulate a world faster or help each other into
+  achieving meaningful results faster.
+- java being used to write the implementation
+
+#### Possible Applications
+
+- studying evolution dynamics
+- discovering new approaches at common problems by looking at how the simulated machines solved them
+- learning how to create the environment necessary for a specific kind of evolution to take place
+- having fun designing such a world and implementing a simulator for it
+- having fun manually designing and creating structures
+- having fun looking at machines interacting with the world and each other
+- bragging about having designed and implemented such a simulation
+- figuring out wether it would actually work
+- distributing a creative alternative to a fish tank
 
 ### World
 
 The world is a matrix where each cell is either empty or occupied by a structure.
 Every structure occupies only one cell.
 
-### Creatures and other structures
+### Structures and Creatures
 
-A structure is a matrix where each cell is either empty or occupied by a Block.
+- a structure is a matrix where each cell is either empty or occupied by a Block.
-Each adiacent Block can be connected.
+- each adiacent Block can be connected.
-The blocks make up both the body and, if the blocks are connected, the mind.
+- the blocks make up both the body and, if the blocks are connected, the mind.
+- structures can move in the world, but can't occupy the same space of another structure.
 
 A structure with an operational mind governing the body is called a creature or machine.
 
 There are four kinds of blocks:
-- neuron blocks
+- __neuron blocks__ make the calculations
-- action blocks
+- __action blocks__ let a structure do something
-- sensor blocks
+- __sensor blocks__ let a structure know something about itself or anything else
-- resource blocks
+- __resource blocks__ can be interacted with, causing some effects
-
-### Connection
-
-- Each block can be connected to every other adiacent block (diagonals too), so each block has 8 connection weights.
-- A connection _is_ a weight, which is a floating point number.
-- A neuron block's output is its adiacent blocks's current stored signals multiplied by the appropriate weight.
-- If the connection is `0`, then there's no connection
-- if the connection is `not 0` then there is a connection
-- the highest `abs(val) where val is the connection/weight` is, the stronger the connection
-- the weight (or connection) is a floating point number between -1 and 1 included.
 
 ### Signals
 
-A signal is a floating point value. Each block stores a signal.
+- a signal is a floating point value. Each block stores a signal.
+- a signal is always between -1 and 1 included.
 
-- new blocks contain the `0` signal (null signal).
+### Connection
-- blocks store a signal forever or until it is changed.
+
+- Each block can be connected to every other adiacent block (diagonals too),
+  so each block has 9 input connection weights: one for each neighbor and one for itself.
+- A connection _is_ a weight, which is a floating point number. All connections are _inputs_.
+- A neuron block's output is its adiacent blocks's current stored signals multiplied by the appropriate weight.
+- the weight (or connection) is a floating point number between -1 and 1 included.
+- If the connection is `0`, then there's no connection
+- if the connection is `not 0` then there is a connection
+- if the connection is `1` then there is a full positive connection, meaning the source value passes
+  intact to the destination
+- if the connection is `-1` then the exact opposite of the input value passes to the destination
+- the highest `abs(val) where val is the connection/weight` is, the stronger the connection
 
 A signal can be any floating point value between -1 and 1.
 
@@ -51,7 +74,11 @@ A signal can be any floating point value between -1 and 1.
 
 ### Neuron (Processing) Blocks
 
-Their signal is the sum of all the values provided by their input connections.
+- new neuron blocks contain the `0` signal (null signal).
+- neuron blocks store a signal until it is changed. The signal is calculated again at every iteration of the
+simulation
+- a neuron block's signal is the sum of all the incoming values, divided then by the sum of all the weights.
+    - an incoming value is the signal coming from a connection multiplied by the connection weight.
 
 ### Action (Output) blocks
 
@@ -85,10 +112,7 @@ They act as Sensor blocks and Action blocks at the same time.
 Examples:
 
 - a "mouth" block that can communicate wether food is available to eat and can receive eat
-commands at the same time
+  commands at the same time
-- a memory block, which has a connection that when activated enables writing the value from
-another connection in the block, then it just outputs its stored value.
-
 
 ### Evaluating a machine's mind's iteration
 
@@ -122,7 +146,7 @@ When the egg hatches, a structure is born. The structure is built using a combin
 
 This requires some new blocks:
 
-- the battery block
+- the battery block (first mentioned resource block)
 - the energy drain block
 - the generator block
 - the stomach block
@@ -131,13 +155,28 @@ This requires some new blocks:
 - the battery block stores energy and emits the current level to its connections
 - the generator block uses up a lot of energy, then gives back slightly more
 - the stomach block can be used to eat blocks from another structure. It then uses some energy to digest
-the blocks, providing it back with an extra amount after it's done. 
+  the blocks, providing it back with an extra amount after it's done. 
 
 #### Consumption
 
 - each action block uses up a moderate amount of energy when activated
 - each sensor block uses up a small amount of energy when activated
 
+## Fitness of a structure
+
+The fitness is calculated by dividing the creature's total harvested energy by the creature's total consumed energy.
+
+A creature with a fitness lower than or equal to 0 has all its batteries depleted. Then, it is
+either revived by being charged somehow, or it can't do anything and no mind activity can take place.
+
+This method to calculate fitness has many problems:
+
+- What if a creature donates energy to others of the same species? It gets counted as energy consumption,
+  thus decreasing fitness
+- What is a creature couldn't harvest energy because the circumstances weren't favorable?
+
+The conclusion is that this system is far too complex to consider fitness evaluation.
+
 ## Primordial world
 
 The world should be composed of a variety of huge, small and anything in between energy farming or storage
@@ -163,11 +202,18 @@ even early in an implementation. We __don't__ want to lose good machines!
 ## Interface
 
 - navigate world
-    - has a small _selected structure_ sidebar with additional information
+    - lets the user create an empty structure (needs at least 1 block)
 - navigate structure
     - ability to save the structure to file
     - has a small _selected block_ sidebar with block informaton
+    - lets the user clear cells or set a block to them
 - view block
     - provides all info about the block and maybe signal activity monitoring
+    - lets the user view all connections and edit them
+    - lets the user edit the block type, preserving the connections
 
-controls to handle simulation speed and pausing.
+A sidebar has controls to handle simulation speed and pausing and other information such as:
+
+- current CPU load.
+- available energy in the world and amount being generated
+- population information