## The Instruction Set File

An instruction set file consists of a list of instructions that belong to that instruction set, each of which is followed by a series of numbers that define how that instruction should be used. These numbers in order are:

[redundancy] | The frequency of the instruction in the set. One instruction with twice the redundancy of another with also have twice the probability of being mutated to. A redundancy of zero is allowed, and indicates that injected organisms are allowed to have this instruction, but it can never be mutated to.
[cost] | The number of CPU cycles required to execute this instruction. One is the default if this value is not specified.
[ft_cost] | The additional cost to be paid the first time this instruction is executed. This is used to lower the diversity of instructions inside an organism. The default value here is 0.
[prob_fail] | The probability of this instruction not working properly. If an instruction fails it will simply do nothing, but still cost the CPU cycles to execute. The defailt probability of failure is zero.

Normally only the first column of numbers is used in the file.

### Description of Default Instruction Set

Below are the descriptions of the instructions turned on in the file "inst_set.default". The one-letter codes are assigned automatically to each instruction in the set, so if additional instructions are turned on, the letters given below may no longer correspond to the instructions they are presented with. If more than 26 instructions are in a set, both lowercase and capital letters will be used, and then numbers. Currently, no more that 62 distinct instructions will be represented by unique symbols.

Most terminology below that may not be familiar to you has been given a link to a file containing its definition.

(a - c) Nop Instructions
The instructions `nop-A` (a), `nop-B` (b), and `nop-C` (c) are no-operation instructions, and will not do anything when executed. They will, however, modifiy the behavior of the instruction preceeding it (by changing the CPU component that it affects; see also nop-register notation and nop-head notation) or act as part of a template to denote positions in the genome.

(d) `if-n-equ`
This instruction compares the ?BX? register to its complement. If they are not equal, the next instruction (after a modifying no-operation instruction, if one is present) is executed. If they are equal, that next instruction is skipped.

(e) `if-less`
This instruction compares the ?BX? register to its complement. If ?BX? is the lesser of the pair, the next instruction (after a modifying no-operation instruction, if one is present) is executed. If it is greater or equal, then that next instruction is skipped.

(f) `pop`
This instruction removes the top element from the active stack, and places it into the ?BX? register.

(g) `push`
This instruction reads in the contents of the ?BX? register, and places it as a new entry at the top of the active stack. The ?BX? register itself remains unchanged.

(h) `swap-stk`
This instruction toggles the active stack in the CPU. All other instructions that use a stack will always use the active one.

(i) `swap`
This instruction swaps the contents of the ?BX? register with its complement.

(j) `shift-r`
This instruction reads in the contents of the ?BX? register, and shifts all of the bits in that register to the right by one. In effect, it divides the value stored in the register by two, rounding down.

(k) `shift-l`
This instruction reads in the contents of the ?BX? register, and shifts all of the bits in that register to the left by one, placing a zero as the new rightmost bit, and trunkating any bits beyond the 32 maximum. For values that require fewer than 32 bits, it effectively multiplies that value by two.

(l) `inc` and (m) `dec`
These instructions read in the contents of the ?BX? register and increment or decrement it by one.

(n) `add` and (o) `sub`
These instructions read in the contents of the BX and CX registers and either sums them together or subtracts CX from BX (respectively). The result of this operation is then placed in the ?BX? register.

(p) `nand`
This instruction reads in the contents of the BX and CX registers (each of which are 32-bit numbers) and performs a bitwise nand operation on them. The result of this operation is placed in the ?BX? register. Note that this is the only logic operation provided in the basic avida instruction set.

(q) `IO`
This is the input/output instruction. It takes the contents of the ?BX? register and outputs it, checking it for any tasks that may have been performed. It will then place a new input into ?BX?.

(r) `h-alloc`
This instruction allocates additional memory for the organism up to the maximum it is allowed to use for its offspring.

(s) `h-divide`
This instruction is used for an organism to divide off an finnished offspring. The original organism keeps the state of its memory up until the read-head. The offspring's memory is initialized to everything between the read-head and the write-head. All memory past the write-head is removed entirely.

(t) `h-copy`
This instruction reads the contents of the organism's memory at the position of the read-head, and copy that to the position of the write-head. If a non-zero copy mutation rate is set, a test will be made based on this probability to determine if a mutation occurs. If so, a random instruction (chosen from the full set with equal probability) will be placed at the write-head instead.

(u) `h-search`
This instruction will read in the template the follows it, and find the location of a complement template in the code. The BX register will be set to the distance to the complement from the current position of the instruction-pointer, and the CX register will be set to the size of the template. The flow-head will also be placed at the beginning of the complement template. If no template follows, both BX and CX will be set to zero, and the flow-head will be placed on the instruction immediatly following the h-search.

(v) `mov-head`
This instruction will cause the ?IP? to jump to the position in memory of the flow-head.

(w) `jmp-head`
This instruction will read in the value of the CX register, and the move the ?IP? by that fixed amount through the organism's memory.

(x) `get-head`
This instruction will copy the position of the ?IP? into the CX register.

(y) `if-label`
This instruction reads in the template that follows it, and tests if its complement template was the most recent series of instructions copied. If so, it executed the next instruction, otherwise it skips it. This instruction is commonly used for an organism to determine when it has finished producing its offspring.

(z) `set-flow`
This instruction moves the flow-head to the memory position denoted in the ?CX? register.

### Other available instructions

`h-push` and `h-pop`
These instructions act siminar to `push` and `pop` above, but instead of working with registers, the place the position of the ?IP? on the stack, or put the ?IP? at the position taken from the stack (respectively).

`inject`
This instruction acts similar to `divide`, but instead of splitting off an offspring, it will remove the section of code between the read and write heads, and attempt to inject it into the neighbor that the organism is facing. The template following this instruction will be used; if an exact match is found (with no extre nops in it) in the target organism, the injected code will be placed immediately after that template. Otherwise the command fails, and the code intended for injection is instead discarded.

`rotate-l` and `rotate-r`
These instructions rotate the facing of an organism. If no teplate follows, the organism will turn one cell in the appropriate direction (left or right). If a template is present, it will keep turning in that direction until either it has made a full 360 degree turn, or else it finds an organism that possesses the complement template.

Project hosted by: