diff --git a/docs/Avida-ED-Error-Database.txt b/docs/Avida-ED-Error-Database.txt new file mode 100755 index 0000000..ca47068 --- /dev/null +++ b/docs/Avida-ED-Error-Database.txt @@ -0,0 +1,67 @@ +Flask +SQLAlchemy - MySQL backend + +http://github.com/ruppmatt/AEDeveloper + +Two modes - + Local for debug (flask) + WSGI Apache Module for deployment + +MySQL for AEDeveloper +u/n: aedeveloper +p/w: + + +leviathan.cme.msu.edu + +database is in +cd .. +cd .. +cd /var/www/ +cd wsgi-scripts +cd AEDeveloper +ls -l #to see files +ls -lah #to see . files + +files need to be owned by Apache +so use script +cat update.sh #to see script to update from github and have apache own + +cat aedeveloper.wsgi #to see this protocol that apache uses. + +--------------------------------------------------------------------------- +To add a user +--------------------------------------------------------------------------- +To create a user from the command line use +sudo ./create_user.sh + +create_user.py [-h] username password fullname email +where username and password cannot spaces +fullname can be wrapped in quotes and have spaces + +need root access to add a user. +--------------------------------------------------------------------------- + +Matt uses flask on his machine using start_local.py +need to have mysSQL running. + +Cannot have any print statements when deploy + + + +To restart Apache +sudo apachectl restart #apache control + + +cat update.sh does a restart tat is slightly different + +sudo service apache2 restart + + +I found an abstract for some of the work discussed in the article. + +Immunizing Against Prejudice: Effects of Disease Protection on Attitudes Toward Out-Groups +By:Huang, JY (Huang, Julie Y.); Sedlovskaya, A (Sedlovskaya, Alexandra); Ackerman, JM (Ackerman, Joshua M.; Bargh, JA (Bargh, John A.) +PSYCHOLOGICAL SCIENCE Volume: 22 Issue: 12 Pages: 1550-1556 Dec 2011 +Contemporary interpersonal biases are partially derived from psychological mechanisms that evolved to protect people against the threat of contagious disease. This behavioral immune system effectively promotes disease avoidance but also results in an overgeneralized prejudice toward people who are not legitimate carriers of disease. In three studies, we tested whether experiences with two modern forms of disease protection (vaccination and hand washing) attenuate the relationship between concerns about disease and prejudice against out-groups. Study 1 demonstrated that when threatened with disease, vaccinated participants exhibited less prejudice toward immigrants than unvaccinated participants did. In Study 2, we found that framing vaccination messages in terms of immunity eliminated the relationship between chronic germ aversion and prejudice. In Study 3, we directly manipulated participants' protection from disease by having some participants wash their hands and found that this intervention significantly influenced participants' perceptions of out-group members. Our research suggests that public-health interventions can benefit society in areas beyond immediate health-related domains by informing novel, modern remedies for prejudice. + diff --git a/docs/Avida-ED_workFlowTesting.txt b/docs/Avida-ED_workFlowTesting.txt new file mode 100755 index 0000000..b7d7373 --- /dev/null +++ b/docs/Avida-ED_workFlowTesting.txt @@ -0,0 +1 @@ +Goals for 2017 0829 Avida - Changes - ./run_tests - commit & push then (automated tests) Don‰_ͺt have - No method aside from commit msgs describing changes - no unit tests Add in code commit lists or in the readme file? tagging commits with Av_ED 3.0.2 or what ever - on both Avida and AV_UI so we know what version of Av_ui goes with which version of Avida Core AV_UI - changes - haphazard tests by Diane by hand - commit push - get Jake to test - fixes - commit push with tag. _____________________________________________________________ following JakeΥs readme file on https://github.com/cousi2344/avida-ed-testing/blob/master/README.rst toward the end ran python tests/test_suite_basic.py --setuipath . ExperimentControlsTest(BaseTest); Run the test longer and check to see that nothing bad happened pytest -v pathtotestfile/testfile.py all tests are in the test folder. Individual tests are in each of the following folders. population organism analysis Looking at one test pytest tests/common/common_basic/navigation/basic_nav_test.py mac has forward slashes; mac has back slashes; another example pytest tests/population/population_basic/env_settings/pause_update_test.py changed it to run for 19 instead of 9 updates. Pull stuff to the av_ui folder within avida-ed-testing . venv/bin/activate cd tests _____________________________________________________________ AV_UI change git clone on server add in stand alone packages Test on Server - automated tests - tests done by hand Move Production to Archive (name with version number and date released) Move test to ‰_Οapp‰__ folder - Tag github at this time _____________________________________________________________ Avida-ED change pull av_ui changes push changes notify diane tag when in production ‰_Σ‰ wireframe fry cartoon icons some parts 2d and some parts 3d geneartive and proceedural things in games (Robin) art assests, story, play through a book. Generative games Mindcraft No mans sky small group of people generate a rich environment. Spore - not a good game box car d2 very simple looks crappy. Fry - how to swim at all - evade predators Swim down stream. point sources of pollution Ocean predators gather food - grow Upstream - fish ladders - bears Mating - finding a mate - sexual selection - Robin - much easier - one kind of salmon - swimming blobs - keep the same blobs in all the environments add chemicals speed of flow increase the complexity of Box car 2d - has physics engine \ No newline at end of file diff --git a/docs/Avida-Ed-TestingNotes.txt b/docs/Avida-Ed-TestingNotes.txt new file mode 100755 index 0000000..de585a2 --- /dev/null +++ b/docs/Avida-Ed-TestingNotes.txt @@ -0,0 +1,66 @@ +Avida-Ed-Testing Notes + +Use once all is installed +start virtual environment. + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Python virtual environment. +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +python --version to get default version which is Python 2.7.10 + +which python3 to get the path over version 3 of python + + only do once to set up an virtual environment folder (we called it venv) had to use path +in the folder that holds venv type + + virtualenv -p /Library/Frameworks/Python.framework/Versions/3.6/bin/python3 venv +Running virtualenv with interpreter /Library/Frameworks/Python.framework/Versions/3.6/bin/python3 + +to activate + source venv/bin/activate + +to get out + deactivate + +while virtual environment activated use the following command to install local packages. +Only need to do once when virtual environment is first set up. + pip install -r requirements.txt + +pip = python package installer +pip freeze lists the packages that are installed. + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Python Virtual Environment 2017 August 25 +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +virtualenv --version to check version of virtual environment. + +docs.python-guide.org/en/latest/dev/virtualenvs + a place to get info + +we need to specify which version of python. +virtualenv -p /Library/Frameworks/Python.framework/Versions/3.6/bin/python3 venv + where venv is the folder for info on the virtual environment. + +pip is the package manager + +pip --help to get help on pip + +pip install -r requirements.txt to load requirements. + There may be stuff in the requirements file that we really don’t need. + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Actual Testing Notes +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +to activate virtual environment + source venv/bin/activate + +then try +python tests/suite.py --setuipath ../av_ui + + + + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +semantic ui as a package to help with Avida-ED 3 + diff --git a/docs/Avida-Resources.txt b/docs/Avida-Resources.txt new file mode 100755 index 0000000..beb0872 --- /dev/null +++ b/docs/Avida-Resources.txt @@ -0,0 +1,69 @@ +Avida from the command line. + +There are several "main"s in avida. + +source/targets/viewer-text/viewer-text.cc + not used that often - put terminal graphics - world as hash marks. + +source/targets/avida/primative.cc + typical one that folks use that is where "main" is + + Abstraction level for Avida-ED on the mac between that and the rest of Avida. + +There are half implemented versions of avida that Dave left and did not complete. + world object, + cworld - old naming convention (c said it was a class) + still the main work horse + World - (from Dave) new faccet system and the way Avida-ED Mac worked + both worlds are needed. circularly dependent. never separated. + managers are "facets" + + +cAvidaConfig* cfg = new cAvidaConfig(); + - the hard coded version (built in defaults) global config + - all of avida.cfg file set up here with default values. + + +Avida::Util::ProcessCmdLineArgs(argc, argv, cfg, defs); + loads command line arguments + names of files except avida.cfg are in avida.cfg + + + Everything was supposed to be facetted. + generic programming concept that Dave wanted in Avida, but not fully implemented + not sure if it is the same as views. + +Avida::World* new_world = new Avida::World(); + sets up facetted world + +cWorld* world = cWorld::Initialize(cfg, cString(Apto::FileSystem::GetCWD()), new_world, &feedback, &defs); + everything is controlled through cWorld + go in and read the config files. (passing in current directory) + + /******** inside cWorld initialize *******/ + cUserFeedback feedback; + used to have a communication cue. + effected structure of Json project. + looks for messages + +(new Avida2Driver(world, new_world))->Run(); + runs one update at a time. + Avida-ED 3 uses "web" driver. + +in cWorld.cc on line 121 create the world + + if starts with "m" it is a member of the current class (not a local variable) by convention in Avida-ED. + + load on line 128 + +In order speed out time ( there is an delta offset) + + +------------ +Spatial system and the Global resource system. +in the course of an update + the deltas will not be applied then "end of an update" when ever someone wants too. + +---------- +effect of reaction with food does not take place until cell divides. + diff --git a/docs/AvidaNotes.txt b/docs/AvidaNotes.txt new file mode 100755 index 0000000..85874a9 --- /dev/null +++ b/docs/AvidaNotes.txt @@ -0,0 +1,342 @@ +Starting at _dev/avida-notebook/AvidaResourceNotebook + +git clone https://github.com/devosoft/avida.git +cd avida +git checkout AvidaED-Web +git submodule init +git submodule update + + +cat .gitmodules + to see what was put in .getmodules + +The modules are in the /lib folder + +./build_avida avida-ed #puts in the cbuild/work folder + +more options now. + +Do all the git stuff from the terminal. X-code does not always play nicely with git + +DRIVER + +use a feedback object + - user feedback + - - error + - - info + - - warning + - - data new for Avida-ED + +are there any messages that need to be sent + +Logic of the asychreous state - + -previous grid update (stats that av_ui requests + + - handles messages from av_ui + - step update + - stuff goes into evens. + - still event driven application + + +webDriverActions.h + - writes to feedback rather than to a file. + +Only that can be sent to av_ui +come from WebDriverActions.h + place to get info from avida to av_ui +can read in json and write json + +messaging.h + - interface between javascript and avida + - untility to grab stuff. + + +Might also look in applications + +cd apps + 516 cd viewer-webed + 518 cd resources + +prepend.js calls avida-messages.js +avida-messages.js would contain the que, but I dont’ send messages fast enough for there to be a que + +Debug stuff is in avida-messages.js. +the counterpart is WebDebug.h + +macro called debug mode. + + + + +Build Script +./build_avida avida-ed (from main avida folder) + +Need C++ 11 or 14 installed. +gcc 45 and all of clang handles it + +setting up Empscripten again. + +emsdk_portable. + +emsdk script handles everything + +emsdk update reaches out and grabs the info + +./emsdk list tells what is available and what is installed. + +node js +clang +need emscripten + +out of tagged releases right now. + + +./emsdk install (what ever need to pull in) which packages + +emsdk environment. + +put in bash r c file. + +puts in the right environmental files set + +./emsdk_set_env.sh + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Emscripten install notes +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +./emsdk update + +./emsdk list #to see what is available + +./emsdk install latest to install the latest version + +./emsdk activate latest needed to actually use the stuff + +source ./emsdk_env.sh to set up shell variables + +Then need to edit .profile in the home folder to make sure emscripten is in the path +that is put the following line in the .profile file with the correct path +source /Users/dianeblackwood/_dev/emscripten/emsdk-portable/emsdk_env.sh + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +To check on the status of cmake do + which cmake on the command prompt. +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” + +Back to compiling Avida. . . . + +At the command prompt in the following folder /Users/dianeblackwood/_dev/avida/ +First remove the cbuild folder +rm -rf cbuild + β€”β€” note rm -rf * will delete all files/folders on the disk + rm - remove + -rf recursive forcefully + +./build_avida avida-ed-web is the correct build for the web based branch + + +To update avida to use the latest version of av_ui +./update_avui.sh + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +X-Code +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +use [command][shift]o to search for a file or object anywhere in the project +use spy glass on tool bar upper left to find a string + +β€” to build using xcode +Under Applications in the project navigator + - click on viewer-webed + then in center area look under TARGETS + - click on viewer-webed +The arguments must be $(ACTION) avida-ed-web + +icons on uppper left (cartoon dialog = report navigator) + +Product menu -> Clean delete the cbuild folder. + +then hit play button (right pointing triangle) +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Cmake +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +cmake --version + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Path +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +changing files to update the path. +env|grep -i path to list the path var +export PATH=β€œ${PATH}:/new/path” per session +or +modify ~/.profile w/ above + +source the file or open new shell + +Change the .profile file in the home directory +cd to get to home directory +ls -a to display .files + +open a new terminal session +or type +source .profile to get the new path or any other new stuff in .profile + +echo ${PATH} to see the current path + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Node.js was installed at + + /usr/local/bin/node + +npm was installed at + + /usr/local/bin/npm + +Make sure that /usr/local/bin is in your $PATH. +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +VIM +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +vim filename to open vim with a certain file. +[esc]i to insert +[escape] to leaven insert mode +[shift]:wq to have command prompt; write; quit + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +command prompt +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +md5 build_avida to get hash number +pwr to get what folder one is in +cd to change folder to home or root +cat to concatenate files, but just list one then it gives a listing +ls to get a folder listing +ls -alh listing with all files; long version; human readable file size +ls -lh long version; +nameOfExecutableFile --version to get a version number +which nameOfFile +mv move to change the file or folder name. +&& to put more than one command on the same line. if one command fails it does not do the next command +& to something in background as a batch +can use | to redirect stuff to another program +3 streams = input stream, output stream and error stream + +ln creates a soft link -s means soft + ln -s ~/_dev/avida/cbuild/work/ av_ui + +file/dir soft link + points to nothing if file deleted. + hard link still retains the block. if there are any hard links to a file it still exists, bust with one fewer names + soft link does not retain the file if the file is deleted (file exists as long as there is the original name or a hard link + The original name is a hard link sort of +man ls gives you the manual for ls = man works for many other commands. +q to quit out of man +less and more work the same way and show you part of a file. + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Error logging 2017 August 25 +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +av_ui (web page) +^ +| +v +Avida Core (Web worker) +^ +| +| +v +WS_server (python) + - /Logger (web page) + localhost:5000/logger + - /Command + localhost:5000/command + - /executor (web page) a way to send commands without using av_ui + localhost:5000/avida + +/avida on lines between Avida CORE and WS_Server + +and WS_Server and /executor + +AEDBridge (name of the project) + - WebSocktes for duplex coms + - Needs server provided by flask + - python 3 + + +logger displays stuff that is normally disabled in avida. +C_ (MODE, STMT, VERBOSITY) +displays on a webpage. + +β€”β€”β€”β€” +To enable + - modify WebDebug.h + to turn on debug statements + - modify messages.js + to enable websocket + +β€”β€”β€”β€” +Redis is the name of the database all stored in memory that the WS_SERVER uses. + + + +This is all in a python virtual environment. + + +β€”β€”β€”β€”β€”β€”β€” + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Redis 2017 August 25 +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” + +./redis-server --port 5060 + + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Git help for Github +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +git checkout build_avida to revert back version on website. +https://chris.beams.io/posts/git-commit/ + +git reset --hard to get rid of changes made to local folder + + + +git submodule init && git submodule update + +git checkout AvidaED-Web puts me in the AvidaED-web branch + +https://chris.beams.io/posts/git-commit/ + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Changing how we calculate averages for population stats 2017 August 25 +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +#In the root directory +./update_avui.sh gets latest av_ui from git hub an stages them to go in the next update + +#Then build + +#When tested add the changes and commit +git add apps/viewer-webed/src/WebDriverActions.h +git add cbuild/bin/* +git commit #Add comments in editor when it pops up and exit +git commit -m β€œ the comments β€œ +git push +#Email Diane + + +Matt uses Dr. Gein for a dentist - in his 70s and is semi-retired +Yancy Tygesen on Jolly Road Okemos oral surgeon + + +β€”β€”β€”β€” + +Avida building avida cleanly Commit change in Avida - Clean builds - - Remove cbuild folder - - - rm –rf cbuild or + ./build_avida clean +- - now actually build avida for regular C ./build_avida + +- - now build avida for avida-ed-web (emscripten) + ./build_avida clean && ./build_avida avida-ed-web + + + diff --git a/docs/AvidaResourcesNotebookNotes.txt b/docs/AvidaResourcesNotebookNotes.txt new file mode 100755 index 0000000..76ade90 --- /dev/null +++ b/docs/AvidaResourcesNotebookNotes.txt @@ -0,0 +1,90 @@ +Starting at _dev/avida-notebook/AvidaResourceNotebook + +git clone https://github.com/ruppmatt/AvidaResourceNotebook.git + +cd AvidaResourceNotebook && git clone https://github.com/devosoft/avida && cd avida && ./build_avida && cd .. && virtualenv -p `which python3` venv && . venv/bin/activate && pip install -r requirements.txt && ln -s ../avida/cbuild/work/avida default_config/avida && cd default_config && ./avida && cd .. + + in ~/_dev/avida-notebook/avidaResourceNotebook +git submodule init && git submodule update +------- + + or all at once +git clone https://github.com/ruppmatt/AvidaResourceNotebook && cd AvidaResourceNotebook && git clone https://github.com/devosoft/avida && cd avida && ./build_avida && cd .. && virtualenv -p `which python3` venv && . venv/bin/activate && pip install -r requirements.txt && ln -s ../avida/cbuild/work/avida default_config/avida && cd default_config && ./avida && cd .. + then in ~/_dev/avida-notebook/avidaResourceNotebook +~/_dev/avida-notebook/avidaResourceNotebook + + + At that point you can launch the notebook by: +jupyter notebook + +-------------------------------- +git clone https://github.com/devosoft/avida.git +cd avida +git checkout AvidaED-Web +git submodule init +git submodule update + + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +VIM +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +vim filename to open vim with a certain file. +[esc]i to insert +[escape] to leaven insert mode +[shift]:wq to have command prompt; write; quit + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +command prompt +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +md5 build_avida to get hash number +pwr to get what folder one is in +cd to change folder to home or root +cat to concatenate files, but just list one then it gives a listing +ls to get a folder listing +ls -alh listing with all files; long version; human readable file size +ls -lh long version; including where a soft link goes +nameOfExecutableFile --version to get a version number +which nameOfFile +mv move to change the file or folder name. +&& to put more than one command on the same line. if one command fails it does not do the next command +& to something in background as a batch +can use | to redirect stuff to another program +3 streams = input stream, output stream and error stream + +ln creates a soft link -s means soft + ln -s ~/_dev/avida/cbuild/work/ av_ui + +file/dir soft link + points to nothing if file deleted. + hard link still retains the block. if there are any hard links to a file it still exists, bust with one fewer names + soft link does not retain the file if the file is deleted (file exists as long as there is the original name or a hard link + The original name is a hard link sort of +man ls gives you the manual for ls = man works for many other commands. +q to quit out of man +less and more work the same way and show you part of a file. + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Off Topic +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Genetics +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” + +Greta Kaplan I've never seen this dog: If I've read the thread right the dog is reported to be Bb KyKy ataw EmE DD. + +Bb - the base color is black rather than liver and should have black nose, toe pads and nails unless there is white spotting of some form which is not included above. Greta's description as black tricolor - indicates she is a black and tan with white which is consistent with B-kykyat-E-D-. + +KyKy - allows expression at the A loci and is NOT brindle. + +At indicates tan points. The Aw indicates wild type. Generally in the Agouti series Ay > Aw > at > a +If the dog looks like a blacktri, then I'd question the aw, typically a black-tri would be atat or ata + +Em - indicates a mask, E is just normal extension = dog can produce both types of pigment + there is a lot of variation in masks + +DD - no dilution + diff --git a/docs/AvidaSpacialResoureAnimation.txt b/docs/AvidaSpacialResoureAnimation.txt new file mode 100755 index 0000000..d736cd3 --- /dev/null +++ b/docs/AvidaSpacialResoureAnimation.txt @@ -0,0 +1,215 @@ +This worked for me to set up Matt's ResouceNotebook. I did have python already installed. + +Quickest start: + +Go to the directory where you'd like to install the repository. Make sure that there is not already a directory called AvidaResourceNotebook present. Then paste and run this in the terminal: + +git clone https://github.com/ruppmatt/AvidaResourceNotebook && cd AvidaResourceNotebook && git clone https://github.com/devosoft/avida && cd avida && ./build_avida && cd .. && virtualenv -p `which python3` venv && . venv/bin/activate && pip install -r requirements.txt && ln -s ../avida/cbuild/work/avida default_config/avida && cd default_config && ./avida && cd .. + +At that point you can launch the notebook by: + +jupyter notebook + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Avida resources animations +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +To build avida go to avida-projects/avida and run +./build_avida + + + +folder structure for this project +avida-projects/ + resources/ + avida/ soft link to avida under work in avida folder below + venv/ + avida/ + cbuiid/ + work/ + avida + *.cfg + *.org + +to set up softlink go to the resources/avida folder + +ln -s ../../avida/cbuild/work/avida . +cp ../../avida/cbuild/work/*.cfg . +cp ../../avida/cbuild/work/default-heads.org . + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Files: in general +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +analyze.cfg - for analyze mode (avdia -a) can be blank, but needs to exist + utility to analyze after the fact. can be blank, but must exist. +avida.cfg - global configuration +environment.cfg +eventts.cfg +instset-heads.cfg - instruction set list +default-head.org default ancestor + +not using the following so we removed them + >rm instset-heads-sex.cfg instset-transsmt.cfg + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Getting Jupyter on Computer +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +I’m putting this in a folder called avida-projects +Create virtual environment by going to the folder where the virtual environment will be crated and running: + >virtualenv -p /Library/Frameworks/Python.framework/Versions/3.6/bin/python3 venv + +Then activate the virtual environment + >source venv/bin/activate + +path for python3 might be different on a different computer. + +Matt then supplied requirements.txt file that goes in the avida-stuff folder + +So then in the same folder run + >pip install -r requirements.txt + +Matt also provided Animate Spatial Resources.ipynb + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” + to run jupyter python notebook +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” + +activate the virtual environment if that has not been done already + >source venv/bin/activate + +python -m jupyter notebook + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +In the Notebook +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +TO run: In the Cells dropdown menu, Click β€œRun Cells” + or to run the cell that one is currently in + +In [ ] beside the cell gives some status information +empty = never executed +[#] what order it was executed (such as [1] +[*} executing or about to be executed + + +To start clean use the Kernel menu +python is single threaded + - interupt will stop the kernel (stop running) + - + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Command Mode: +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +When the vertical line on the left is blue, it is in command mode +h: gives some command listings + got me into command mode + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Typing Mode +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +The vertical line on the left is green +clicking in the cell put it in this mode. + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Test to see that avida runs +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +go to avida-projects/resources/avida + >./avida + +to clear the data folder (output created when running avida) + >rm -rf data +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +First Experiment with one non-reproducing organism and let resources flow +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” + +Files +analyze.cfg - for analyze mode (avdia -a) can be blank, but needs to exist +avida.cfg - + disable mutations + disable death + +environment.cfg + +eventts.cfg + only inject + printSpatial Resources + Exit + +instset-heads.cfg - (add nop-x to end) + +default-head.org default ancestor + replace + h-divide w/ nop-x + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +vim notes +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +vim cheatsheet on line to find more help on vim + +vim filename + + put in command mode + +in commmand mode + G - puts at end of file + gg - goes to the top + o - opens an new line below and goes into insert mode + O - opens a new line above the current line and goes into insert mode + i - goes into insert mode + :wq - write quit the colon is important + R - replace mode + 0 - go to the start of the line + $ - go to the end of the line + / - begin search process + :nohls to get rid of highlighting from search + :19 jumps to line 19 for example +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” + +https://docs.google.com/spreadsheets/d/1ZS9OT1Om0PYd_ePamXXgr1MhGPrC7ZcvP-7rUCqq7Gs/edit#gid=0 + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” + +Asking Students about Nature of Science +β€œScience and the Citezin” +Nature and Process of Science” +General Education at the college level - Utah State regional campus (20 students) +Mike will interview over Zoom in December + +how does this fit into experimental design. +Nature and Practice of Science. + + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +git reset --hard to revert back to last clone commit or pull or clone +git reset --hard origin/master to pull to latest and erase local changes. + origin is the name of the remote (git hub) branch + +start virtual environment + . venv/bin/activate + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Info about how the python notebook works. + +Currently developing on avidares +this is a package because it has a file called __init__.py +not full, because there is no setup.py file that would let .pip install it (part of the Easy_setup) + +avidares.SingleExperiment is getting SingleExperiment is module (file) withing the package avidares + +classes in SingleExperiment that mostly use + ResourceExperiment. + ResourceExperimentAnimation + + +classes in FactoredExperiment that mostly use + ResourceFactoredExperiment + ResourceFactoredExperimentIterator + ResourceFactoredExperimentAnimation + + + + + diff --git a/docs/C++notes.txt b/docs/C++notes.txt new file mode 100755 index 0000000..3fbaa89 --- /dev/null +++ b/docs/C++notes.txt @@ -0,0 +1,53 @@ +2017 Aug 16 +onstructor + Copy constructor + assignment onstructor (=) + destructor +β€”β€”β€”β€”β€”β€”β€” + +Implementing an Action + - - write constructor + - - implement GetDescription (. . .) + - - implement Process (. . .) + - - if needed destructor + + +in avida cfg file + +u 0 [_____________} +0 is an update number +[__________] is the name of a cAction + +u start:interval:end [_______] [args] + +args = usually copied to a new string typically called Largs in constructor) +called m_args internally (class member internal to that class) + +class member by convention indicated by m_ + + +β€”β€”β€” + +for web interface we have cWebAction + +cAction (virtual) + | + v +cWebAction (virtual) + | + v +cWebActionSomething (implemented) where something is the name. + + +allows us to use +- json args +- feedback option for data +- packaging data utility + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +Organism + <β€” phnotype + <- genotype + <- hardware + + diff --git a/docs/Evosphere_2017_1207.txt b/docs/Evosphere_2017_1207.txt new file mode 100755 index 0000000..d46293c --- /dev/null +++ b/docs/Evosphere_2017_1207.txt @@ -0,0 +1,248 @@ +Experiments script + environment + populations + one or more + individual organisms (rovers) + build method on rovers + using factories (reflection with factory rather than actual thing) + + +Robin + +When start play + +2 phases (set up and Loop) + +Setup + +Loop of following to blocks +Start Generation +running phase +replicate phase + +When press play + deserializing + calling a bunch of factories + makes some game objects + +Life Cycle of an organism + - Spawn + - build + - running (not the update functions) + running is called in the experiment's update function + control to not skip frames + +Structure of mono 0 behaviors + +Game Object (location in the world) + can have stuff attached. + mono-behaviors attached. + (code to excute) + + +Mono-behavior is a class + with virtual methods + called by unity engine in an opaque way. + don't worry about how. + wake ( called unconditionally) called as soon as estangiaged. + start (only after exists in the world) + enabled and disabled + update function (called kind of like every frame but not locked to physics engine) + +Fixed updated to the physics engine, but not fixed to the update rates + rendering is expensive - + physics is often faster than the rendering + rendering pushing to gpu one bit at a time (not in parallel) + Unity obscures stuff. + appear to running in a single thread (but not really) + +Multiple event listeners + +void Awake() { + this.enable=clase; +} + +spawning is expensive. + - avoid spawning when possible. + try not to spawn new things + +Expensive to create new object; cheap to change object. + so reuse object rather than kill and spawn again + + +Running will not happen before building is done + +bodies will be spawned, but the controller will not be spawned. + + +for x in org.Build() { + yield return x; +} +add org to running list + (keeps running till it dies) + +synchronous - all born and die as a group. + selective pressure to be constructed faster if the don't specifically wait for slow builders before running the group. + +Need to know when an organism wants to replicate. + +Jake left so beginner + +Game Objects + - core thing + does not do anything. does not even have a position + - can have multiple components attched to it. + each one is a C# class + access the components with a api +All of the objects get a transform objects + model view mattricies (positional spatial information) + + + +Quaternions - a generization of complex numbers + complex number = real + complex * i + a1 + a2*i + a3*j + a4*k where (1, 2, 3 are subscripts and i, j, k are vectors) + can be restricted to a subset with magnitudes of 1 + Eular coorinates can have gimble lock. + +meshes and physics objects. + change looks or physics behavior or mono-behaviors. + +Exercise to make a simple game in unity +drive ball around in push things and events trigger when it hits things. + +re-implement the rovers. Make changes to rovers. +re-do the make command and have it pop up in the user interface. + +do some live coding of implementing something. + + + + + + + + +2017_1208 Charles Meeting + +Three parts of contribution to paper +1. Intellecturally + +2. data generation (including statistics) + +3. writing/editing + + +Author - made the paper happen as opposed to not happen. +making it rise to higher level quality. + + +Literature Review - conceptual + + +Seeds should be different. + +every treatment should have unique seed. + +Avida (0= random number based on time) + another number - random number base on that seed. + +Josh example +Compare high mutation rate to low mutation rate +should be completely different. + +If doing paired runs, perhaps. + +if you want same initial conditions go out of way to make sure that is true. Don't assume that using the same random seed will do that for you. + +Reusing seeds from one treatment to another should not mater. + +Leslie Moore never re-used the same seed from experiment to the next. + +Paired runs with paired statistics. +If use the same seed - do intentionally and know what you are doing. + + +# 9 Proffesor asked to review a paper that they know from seeing at conference, but not otherwise. Concerned about ideas effecting their own research. implied belief that ideas will not be stolen by the reviewer. Is it wrong to have a head start. +People worried about being scooped. + + +Data Matching + Rodan - + + +python library to access git history. + +troll git histories when doing search . + +Rose (used evernote for a while) +Noodle - lab notebook. + Rose wrote Noodle (CK editor) saves to html files + python script with flask (attaches to port 5000 + search is grep based. + +Scientific keeping in journals. + - personal notes and commenatary separate. + - win a nobel prize - notebook published + - if random personal shit in notebook needs to be stated as such. + +- helps keep things in context to note some stuff read +- don't put patentable on web unless you want to prevent someone else from patententable. Who ever files first unless it has been made public. Special paper notebooks + +Evernote had good handwriting recognition - can +silver note (only for PCs) + +Experimental treatment description +discussion of what + + +Struture in Log form and search for projects. + + +Links in log to notebooks. + +iPython notebook. +Discussion in Noodle. + +Tagging is a big thing. + +When does one save full data and when can you just save the configuration to generate the data. + +Published paper. Lots of fitness data throughout the data. all average in the paper. + + +Python Library called bump version major or minor push tags to git hub. + + +Not sure what version that you have done a run on . + + +Do a final data run after all stat exploration, ideas, etc done. + + +Time for lab meeting for next semester. Push to slack. +---------- + +University Lawyer. + solisitation of copywrited material + doing wrong stuff, vs. knowingly knowling doing wrong stuff. + +People to inform students of what is allowed and what is not allowed. Will talk to legal stuff at other big 10 conference. +Send a notice that the majority of their stuff is copywrited. + +other proposed solutions + - Chad is used for cheating + - Provost looking into what can be done to students for posting course content to Chag??? 2000 level students caught cheating + - plagerism is not technically against the law? + + - normal accounts cannot post solutions. + - posting questions and using the answers + - solutions posted for low level courses are reasonable. + +Looking new omnibussman at MSU + +following Monday a week Party for Rose. +No lab meeting next year. + +Bliss Salon and Jamie Fenriss +near Myer on Saginaw west side near 69/96 \ No newline at end of file diff --git a/docs/Ofria-Charles.1500-768x960.jpg b/docs/Ofria-Charles.1500-768x960.jpg new file mode 100755 index 0000000..9922613 Binary files /dev/null and b/docs/Ofria-Charles.1500-768x960.jpg differ diff --git a/docs/SettingUpAvida-EDonServer.txt b/docs/SettingUpAvida-EDonServer.txt new file mode 100755 index 0000000..c3059d9 --- /dev/null +++ b/docs/SettingUpAvida-EDonServer.txt @@ -0,0 +1,10 @@ +On Texas Server + +degas2.fdisk.net +/var/www/vhosts/avidaed/public_html/app +get password from Wesley or Marc + +On MSU server + Pulse Secure must be running if off campus +leviathan.cme.msu.edu +/var/www/avida-ed.beacon-center.org/app diff --git a/docs/documentation/About.md b/docs/documentation/About.md new file mode 100644 index 0000000..253fac8 --- /dev/null +++ b/docs/documentation/About.md @@ -0,0 +1,42 @@ +When studying biological evolution, we have to overcome a large obstacle: Evolution is extremely slow. Traditionally, evolutionary biology has therefore been a field dominated by observation and theory, even though some regard the domestication of plants and animals as early, unwitting evolution experiments. Realistically, we can carry out controlled evolution experiments only with organisms that have very short generation times, so that populations can undergo hundreds of generations within a time frame of months or years. With the advances in microbiology, such experiments in evolution have become feasible with bacteria and viruses [ElenaLenski2003, TravisanoRainey2000]. However, even with microorganisms, evolution experiments still take a lot of time to complete and are often cumbersome. In particular, some data can be difficult or impossible to obtain, and it is often impractical to carry out enough replicas for high statistical accuracy. + +According to Daniel Dennett, "...evolution will occur whenever and wherever three conditions are met: replication, variation (mutation), and differential fitness (competition)"[Dennett2002]. It seems to be an obvious idea to set up these conditions in a computer, and to study evolution ''in silico'' rather than ''in vitro''. In a computer, it is easy to measure any quantity of interest with arbitrary precision, and the time it takes to propagate organisms for several hundred generations is only limited by the processing power available. In fact, population geneticists have long been carrying out computer simulations of evolving loci, in order to test or augment their mathematical theories (see [HartlClark2006, KimStephan2003, McVeanCharlesworth2000, Nowak2006, Orr2000] for some examples). However, the assumptions put into these simulations typically mirror exactly the assumptions of the analytical calculations. Therefore, the simulations can be used only to test whether the analytic calculations are error-free, or whether stochastic effects cause a system to deviate from its deterministic description, but they cannot test the model assumptions on a more basic level. + +An approach to studying evolution that lies somewhere in between evolution experiments with biochemical organisms and standard Monte-Carlo simulations is the study of self-replicating and evolving computer programs (digital organisms). These digital organisms can be quite complex and interact in a multitude of different ways with their environment or each other, so that their study is not a simulation of a particular evolutionary theory but becomes an experimental study in its own right. In recent years, research with digital organisms has grown substantially ([AdamiOfriaCollier2000, ComasMoyaGonzalez-Candelas2005, Egri-NagyNehaniv2003, GerleeLundh2005, LenskiOfriaPennock2003, MisevicOfriaLenski2006, WilkeWangOfria2001, YedidBell2001, YedidBell2002, ZhangTravisano2007], see [Adami2006, WilkeAdami2002] for reviews), and is being increasingly accepted by evolutionary biologists [ONeill2003]. (However, as Barton and Zuidema [BartonZuidema2003] note, general acceptance will ultimately hinge on whether artificial life researchers embrace or ignore the large body of population-genetics literature.) Avida is arguably the most advanced software platform to study digital organisms to date, and is certainly the one that has had the biggest impact in the biological literature so far. Having reached version 2.14, it now supports detailed control over experimental settings, a sophisticated system to design and execute experimental protocols, a multitude of possibilities for organisms to interact with their environment (including depletable resources and conversion from one resource into another) and a module to post-process data from evolution experiments (including tools to find the line of descent from the original ancestor to any final organism, to carry out knock-out studies with organisms, to calculate the fitness landscape around a genotype, and to align and compare organisms' genomes). + +## History of Digital Life + +The most well-known intersection of evolutionary biology with computer science is the genetic algorithm or its many variants (genetic programming, evolutionary strategies, and so on). All these variants boil down to the same basic recipe: (1) create random potential solutions, (2) evaluate each solution assigning it a fitness value to represent its quality, (3) select a subset of solutions using fitness as a key criterion, (4) vary these solutions by making random changes or recombining portions of them, (5) repeat from step 2 until you find a solution +that is sufficiently good. + +This technique turns out to be an excellent method for solving problems, but it ignores many aspects of natural living systems. Most notably, natural organisms must replicate themselves, as there is no external force to do so; therefore, their ability to pass their genetic information on to the next generation is the final arbiter of their fitness. Furthermore, organisms in a natural system have the ability to interact with their environment and with each other in ways that are excluded from most algorithmic applications of evolution. + +Work on more naturally evolving computational systems began in 1990, when Steen Rasmussen was inspired by the computer game "Core War" [Dewdney1984]. In this game, programs are written in a simplified assembly language and made to compete in the simulated core memory of a computer. The winning program is the one that manages to shut down all processes associated with its competitors. Rasmussen observed that the most successful of these programs were the ones that replicated themselves, so that if one copy were destroyed, others would still persist. In the original Core War game, the diversity of organisms could not increase, and hence no evolution was possible. Rasmussen designed a system similar to Core War in which the command that copied instructions was flawed and would sometimes write a random instruction instead on the one intended [RasmussenKnudsenFeldberg1990]. This flawed copy command introduced ''mutations'' into the system, and thus the potential for evolution. Rasmussen dubbed his new program "Core World", created a simple self-replicating ancestor, and let it run. + +Unfortunately, this first experiment was only of limited success. While the programs seemed to evolve initially, they soon started to copy code into each other, to the point where no proper self-replicators survived---the system collapsed into a non-living state. Nevertheless, the dynamics of this system turned out to be intriguing, displaying the partial replication of fragments of code, and repeated occurrences of simple patterns. + +The first successful experiment with evolving populations of self-replicating computer programs was performed the following year. Thomas Ray designed a program of his own with significant, biologically-inspired modifications. The result was the Tierra system [Ray1992]. In Tierra, digital organisms must allocate memory before they have permission to write to it, which prevents stray copy commands from killing other organisms. Death only occurs when memory fills up, at which point the oldest programs are removed to make room for new ones to be born. + +The first Tierra experiment was initialized with an ancestral program that was 80 lines long. It filled up the available memory with copies of itself, many of which had mutations that caused a loss of functionality. Yet other mutations were neutral and did not affect the organism's ability to replicate --- and a few were even beneficial. In this initial experiment, the only selective pressure on the population was for the organisms to increase their rate of replication. Indeed, Ray witnessed that the organisms were slowly shrinking the length of their genomes, since a shorter genome meant that there was less genetic material to copy, and thus it could be copied more rapidly. + +This result was interesting enough on its own. However, other forms of adaptation, some quite surprising, occurred as well. For example, some organisms were able to shrink further by removing critical portions of their genome, and then use those same portions from more complete competitors, in a technique that Ray noted was a form of parasitism. Arms races transpired where hosts evolved methods of eluding the parasites, and they, in turn, evolved to get around these new defenses. Some would-be hosts, known as hyper-parasites, even evolved mechanisms for tricking the parasites into aiding them in the copying of their own genomes. Evolution continued in all sorts of interesting manner, making Tierra seem like a choice system for experimental evolution work. + +In 1992, Chris Adami began research on evolutionary adaptation with Ray's Tierra system. His intent was to have these digital organisms to evolve solutions to specific mathematical problems, without forcing them use a pre-defined approach. His core idea was the following: If he wanted a population of organisms to evolve, for example, the ability to add two numbers together, he would monitor organisms' input and output numbers. If an output ever was the sum of two inputs, the successful organisms would receive extra CPU cycles as a bonus. As long as the number of extra cycles was greater than the time it took the organism to perform the computation, the leftover cycles could be applied toward the replication process, providing a competitive advantage to the organism. Sure enough, Adami was able to get the organisms to evolve some simple tasks, but faced many limitations in trying to use Tierra to study the evolutionary process. + +In the summer of 1993, Charles Ofria and C. Titus Brown joined Adami to develop a new digital life software platform, the Avida system. Avida was designed to have detailed and versatile configuration capabilities, along with high precision measurements to record all aspects of a population. Furthermore, whereas organisms are executed sequentially in Tierra, the Avida system simulates a parallel computer, allowing all organisms to be executed effectively simultaneously. Since its inception, Avida has had many new features added to it, including a sophisticated environment with localized resources, an events system to schedule actions to occur over the course of an experiment, multiple types of CPUs to form the bodies of the digital organisms, and a sophisticated analysis mode to post-process data from an Avida experiment. Avida is under active development at Michigan State University, led by Charles Ofria and David Bryson. + + +## The Scientific Motivation for Avida + +Intuitively, it seems that natural systems should be used to best understand how evolution produces the variation in observed in nature, but this can be prohibitively difficult for many questions and does not provide enough detail. Using digital organisms in a system such as Avida can be justified on five grounds: + +
    +
  1. ''Artificial life forms provide an opportunity to seek generalizations about self-replicating systems'' beyond the organic forms that biologists have studied to date, all of which share a common ancestor and essentially the same chemistry of DNA, RNA and proteins. As John Maynard Smith[Maynard-Smith1992] made the case: "So far, we have been able to study only one evolving system and we cannot wait for interstellar flight to provide us with a second. If we want to discover generalizations about evolving systems, we will have to +look at artificial ones." Of course, digital systems should always be studied in parallel with natural ones, but any differences we find between +their evolutionary dynamics open up what is perhaps an even more interesting set of questions.
    2. +
  2. ''Digital organisms enable us to address questions that are impossible to study with organic life forms''. For example, in one of our current experiments we are investigating the importance of deleterious mutations in adaptive evolution by explicitly reverting all detrimental mutations. Such invasive micromanaging of a population is not possible in a natural system, especially without disturbing other aspects of the evolution. In a digital evolving system, every bit of memory can be viewed without disrupting the system, and changes can be made at the +precise points desired.
    3. +
  3. ''Other questions can be addressed on a scale that is unattainable with natural organisms''. In an earlier experiment with digital organisms [LenskiOfriaCollier1999] we examined billions of genotypes to quantify the effects of mutations as well as the form and extent of their interactions. By contrast, an experiment with ''E. coli'' was necessarily confined to one level of genomic complexity. Digital organisms also have a speed advantage: population with 10,000 organisms can have 20,000 generations processed per day on a modern desktop computer. A similar experiment with bacteria took over a decade [Lenski2004].
    4. +
  4. ''Digital organisms possess the ability to truly evolve, unlike mere numerical simulations''. Evolution is open-ended and the design of the evolved solutions is unpredictable. These properties arise because selection in digital organisms (as in real ones) occurs at the level of the whole-organism's phenotype; it depends on the rates at which organisms perform tasks that enable them to metabolize resources to convert them to energy, and the efficiency with which they use that energy for reproduction. Genome sizes are sufficiently large that evolving populations cannot test every possible genotype, so replicate populations always find different local optima. A genome typical consists of 50 to 1000 sequential instructions. With commonly 26 possible instructions at each position, there are many more potential genome states than there are atoms in the universe.
    5. +
  5. ''Digital organisms can be used to design solutions to computational problems'' where it is difficult to write explicit programs that produce the desired behavior [Goldberg2002,Koza2003]. Current evolutionary algorithm approaches are based on a simplistic view of evolution, leaving out many of the factors that are believed to make it such a powerful force. Thus there are new opportunities for biological concepts to have a large impact outside of biology, just as principles of physics and mathematics are often used throughout other fields, including biology.
    6. +
diff --git a/docs/documentation/Analysis-settings.md b/docs/documentation/Analysis-settings.md new file mode 100644 index 0000000..3498f2b --- /dev/null +++ b/docs/documentation/Analysis-settings.md @@ -0,0 +1,3 @@ +These settings allow you to control the number of analyze threads and to define values that analyze mode can access. + +See avida.cfg for MAX_CONCURRENCY, ANALYZE_OPTION_1, and ANALYZE_OPTION_2. diff --git a/docs/documentation/Analyze-File.md b/docs/documentation/Analyze-File.md new file mode 100644 index 0000000..3a70869 --- /dev/null +++ b/docs/documentation/Analyze-File.md @@ -0,0 +1,1010 @@ +
+

The Analyze File

+
+ +

+The file analyze.cfg is used to setup Avida when it is run in +analyze mode, which can be done by running avida -a. Analyze +mode is useful for performing additional tests on genotypes after a run +has completed. +

+

+This analysis language is basically a simple programming language. The +structure of a program involves loading in genotypes in one or more +batches, and then either manipulating single batches, or doing comparisons +between batches. Currently there can be up to 2000 batches of genotypes, but +we will eventually remove this limit. +

+

+The rest of this file describes how individual commands work, as well +as some notes on other languages features, like how to use variables. As +a formatting guide, command arguments will be presented between brackets, +such as [filename]. If that argument is +mandatory, it will be in blue. If it is optional, it will be in green, and +(if relevant) a default value will be listed, such as +[filename='output.dat']. +

+ +

 

+

Analyze Mode Commands

+ +

+Analyze mode provides a number of commands for loading, manipulating, +and saving analysis data. In addition to the analyze mode specific +commands detailed in the following sections, all of the +Avida actions can be called as well. +

+ +

 

+

Load Commands

+

+There are currently four ways to load in genotypes: +

+
+
LOAD_ORGANISM [filename]
+
+ Load in a normal single-organism file of the type that is output + from Avida. These consist of lots of organismal information inside + of comments, and then the full genome of the organism with one + instruction per line. +
+
LOAD [filename]
+
+ Load in a file that contains a list of genotypes, one-per-line with + additional informaiton about those genotypes. Avida now includes a header + on such files indicating the values containted in each column. +
+
LOAD_SEQUENCE [sequence]
+
+ Load in a user-provided sequence as the genotype. Avida has a + symbol associated with each instruction; this command is simply + followed by a sequence of such symbols that is than translated back + into a proper genotype. +
+
+ LOAD_MULTI_DETAIL [start-UD] + [step-UD] [stop-UD] + [dir='./'] [start batch=0] +
+
+ Allows the user to load in multiple detail files at once, one per + batch. This is helpful when you're trying to do parallel analysis + on many detail files, or else to create a phylogenetic depth map. +
Example: LOAD_MULTI_DETAIL 100 100 100000 ../my_run/run100/ +
+ This would load in the files detail_pop.100 through detail_pop.100000 + in steps of 100, from the directory of my choosing. Since 1000 files will + be loaded and we didn't specify starting batch, they will be put in + batches 0 through 999. +
+
+ +

+A future addition to this list is a command that will use the "dominant.dat" +file to identify all of the dominant genotypes from a run, and then lookup and +load their individual genomes from the archive directory. +

+ + +

 

+

Batch Control Commands

+

+All of the load commands place the new genotypes into the current batch, +which can be set with the SET_BATCH command. Below is the list of control +functions that allow you to manipulate the batches. +

+ +
+
SET_BATCH [id]
+
+ Set the batch that is currently active; the initial active batch + at the start of a program is 0. +
+
NAME_BATCH [name]
+
+ Attach a name to the current batch. Some of the printing methods + will print data from multiple batches, and we want the data from each + batch to be attached to a meaningful identifier. +
+
PURGE_BATCH [id=current]
+
+ Remove all genotypes in the specified batch (if no argument is given, + the current batch is purged. +
+
DUPLICATE [id1] [id2=current]
+
+ Copy the genotypes from batch id1 into id2. By default, + copy id1 into the current batch. Note that duplicate is + non-destructive so you should purge the target batch first if + you don't want to just add more genotypes to the ones already in + that batch. +
+
STATUS
+
+ Print out (to the screen) the genotype count of each non-empty batch + and identify the currently active batch. +
+
+ + +

 

+

Analysis Control Commands

+ +

+There are several other commands that will allow you to interact with the +analysis mode in some very important ways, but don't actually trigger any +analysis tests or output. Below are a list of some of the more important +control commands. +

+ +
+
SYSTEM [command]
+
+ Run the command listed on the command line. This is particularly + useful if you need to unzip files before you can use them, or if + you want to delete files no longer in use. +
+
CLOSE_FILE [filename]
+ Close a file. This is useful for instances where your script creates + lots of unique files using command that support reentrant usage, such + as DETAIL_AVERAGE for example. +
+
INCLUDE [filename]
+
+ Include another file into this one and run its contents immediately. + This is useful if you have some pre-written routines that you want + to have available in several analysis files. Watch out because there + are currently no protections against circular includes. +
+
INTERACTIVE
+
+ Place Avida analysis into interactive mode so that you can type + commands have have them immediately acted upon. You can place this + anywhere within the analyze file, so that you can have some + processing done before interactive mode starts. You can type quit + at any point to continue with the normal processing of the file. +
+
DEBUG [message]
+
ECHO [message]
+
+ These are both echo commands that will print a message (the + arguments given) onto the screen. If there are any variables (see + below) in the message, they will be translated before printing, so + this is a good way of debugging your programs. +
+
+ + +

 

+

Genotype Manipulation Commands

+ +

+Now that we know how to interact with analysis mode, and load in genotypes, +its important to be able to manipulate them. The next batch of commands +will do basic analysis on genotypes, and allow the user to prune batches +to only include those genotypes that are needed. +

+ +
+
RECALCULATE [use_resources=0] [update=-1] [use_random_inputs=0] [env_input.1 env_input.2 env_input.3]
+
+ Run all of the genotypes in the current batch through a test CPU + and record the measurements taken (fitness, gestation time, etc.). + This overrides any values that may have been loaded in with the + genotypes. The use_resources flags signifies whether or not the + test cpu will use resources when it runs. If resources are used, the + update parameter allows setting resource values from a specific time point + in the resource list. For more information on resources, see the + summary below. If the use_random_inputs flag + is set, then organisms will be provided with new, random input strings for + each trace as they would experience during an actual Avida run. By default, + the same inputs are provided every time to organisms in analysis mode. + If additional arguments are specified after use_random_input's value, these + integers will be used as environmental inputs for the genotype's test cpu + recalculation. Manually specified test cpu inputs must conform to the pseudo-random + formatting described in cEnvironment::SetupInputs. Phenotypic plasticity information is not available from the + RECALCULATE command; use RECALC with num_trials X, where X is greater than 1, + for phenotypic plasticity statistics. +
+
RECALC [use_resources] [use_random_inputs] [update N (N=-1)] [use_manual_inputs input.1 input.2 input.3] [num_trials T (T=1)]
+
+ This command will perform the same operations as RECALCULATE but has a few additional features. + Instead of having a specified ordering for inputs to this command, argument order does not matter. + To use resources, for instance, use the flag use_resources following RECALC. + Arguments with parameters must have the values specified immediately after them. For instance +
+    RECALC update 10 use_resources use_manual_inputs 256948023 870730840 1441302276 +
+ will set the update to 10, request the use of resources, and test the genotypes using the inputs 256948023, 870730840, and 1441302276. Manually specified environment inputs must conform to the pseudo-random numbers as + described in cEnvironment::SetupInputs. + Typically, use_manual_inputs will override use_random_inputs, however if num_trials is set to greater than one, manual input specficiation will be overriden + and random inputs will be used to gather phenotypic plasticity information that will be available + for genotype statistics at the bottom of this document. Please note that phenotypic plasticity + analysis perfoemd by using RECALC will reset genotype statistics to the values for the most likely + phenotype. Implicit phenotypic plasticity analysis (e.g. by not calling RECALC or calling RECALC with num_trials 1) + will not re-evaluate the genotype statistics in this manner and instead rely on the initial values or + those values from a single recalculation. +
FILTER [stat] [relation] [test_value] [batch=current]
+
+ Perform the given test on all genotypes and Remove all those that do not pass. Stat indicates which + metric you want to compare, relation is the test to perform (==, !=, <, >, <=, or >=), and + test_value is the value to compare it to. For example
+   FILTER fitness >= 1.5
+ will save only those genotypes with a fitness greater than or equal to 1.5. Set the section on + Genotype Statistics for more information on what keywords can be used here. +
+
FIND_GENOTYPE [type='num_cpus' ...]
+
+ Remove all genotypes but the one selected. Type indicates which + genotype to choose. Options available for type are num_cpus (to + choose the genotype with the maximum organismal abundance at time of + printing), total_cpus (number of organisms ever of this genotype), + fitness, length, or merit. If a the type entered is numerical, it is + used as an id number to indicate the desired genotype (if no such id + exists, a warning will be given). Multiple arguments can be given to + this command, in which case all those genotypes in that list will be + preserved and the remainder deleted. If no argument is passed for type, it uses max num_cpus as default. +
+
FIND_ORGANISM [random]
+
+ Picks out a random organism from the population and removes all + others. It is different from FIND_GENOTYPE because it takes into + account relative number of organisms within each genotype. To pick + more than one organisms, list the word 'random' multiple times. This + is essentially sampling without replacement from the population. +
+
FIND_LINEAGE [type="num_cpus"]
+
+ Delete everything except the lineage from the chosen genotype back + to the most distant ancestor available. This command will only + function properly if parental information was loaded in with the + genotypes. Type is the same as the FIND_GENOTYPE command. +
+
+ FIND_SEX_LINEAGE [type="num_cpus"] + [parent_method="rec_region_size"] +
+
+ Delete everything except the lineage from the chosen genotype back + to the most distant ancestor available. Similar to FIND_LINEAGE but + works in sexual populations. To simplify things, only maternal lineage plus + immediate fathers are saved, i.e. info about father's parents is discarded. + The second option, parent_method, determines which parent is considered the + 'mother' in each particular recombination. If parent_method is "rec_region_size" : + 'mother' is the parent contributing more code to the offspring genome + (default); if it's genome_size, 'mother' is the parent with the longer + genome, no matter how much of it was contributed to the offspring. + This command will only function properly if parental information was + loaded in with the genotypes. Type is the same as the FIND_GENOTYPE command. +
+
ALIGN
+
+ Create an alignment of all the genome's sequences; It will place '_'s + in the sequences to show the alignment. Note that a FIND_LINEAGE + must first be run on the batch in order for the alignment to be + possible. +
+
SAMPLE_ORGANISMS [fraction] [test_viable=0]
+
+ Keep only fraction of organisms in the current batch. This + is done per organism, not per genotype. Thus, genotypes of high + abundance may only have their abundance lowered, while genotypes + of abundance 1 will either stay or be removed entirely. If test_viable is + set to 1, sample only from the viable organisms. +
+
SAMPLE_GENOTYPES [fraction] [test_viable=0]
+
+ Keep only fraction of genotypes in the current batch. If test_viable is + set to 1, sample only from the viable genotypes. +
+
RENAME [start_id=0]
+
+ Change the id numbers of all the genotypes to start at a given value. + Often in long runs we will be dealing with ID's in the millions. In + particular, after reducing a batch to a lineage, we will often want + to number the genotypes in order from the ancestor to the final one. +
+
+ + +

 

+

Basic Output Commands

+ +

+Next, we are going to look at the standard output commands that will used to +save information generated in analyze mode. +

+ +
+
PRINT [dir='archive/'] [filename]
+
+ Print the genotypes from the current batch as individual files (one + genotype per file) in the directory given. If no filename is specified, + the files will be named by the genotype name, with a .gen appended to + them. Specifying the filename is useful when printing a single genotype. +
+
TRACE [dir='archive/'] [ use_resources=0] [update=-1] [ use_random_inputs=0] [env_input.1 env_input.2 env_input.3]
+
+ Trace all of the genotypes and print a listing of their execution. + This will show step-by-step the status of all of the CPU components + and the genome during the course of the execution. The filename used + for each trace will be the genotype's name with a .trace appended. + The use resources flag signifies whether or not the test cpu will use + resources when it runs. If resources are used, the update parameter allows + setting resource values from a specific time point in the resource list. + For more information on resources, see the summary below. + If the use_random_inputs flag is set, then organisms will be provided with new, + random input strings for each trace as they would experience during an actual Avida run. + By default, the same inputs are provided every time to organisms in analysis mode. You can + manually specify environmental inputs by setting use_random_inputs to 0 setting env_input.X + values. Manually specified environment inputs must conform to the pseudo-random numbers as + described in cEnvironment::SetupInputs. +
+
PRINT_TASKS [file='tasks.dat']
+
+ This will print out the tasks doable by each genotype, one per line + in the output file specified. Note that this information must either + have been loaded in, or a RECALCULATE (or RECALC) must have been run to collect + it. +
+
+ PRINT_PHENOTYPES [file='phenotype.dat'] + [total_task_count] + [total_task_performance_count] +
+
+ Prints phenotypes in the current batch as determined by task-signature. Default statistics for each phenotype are number of organisms, number of genotypes, average genome length, average gestation time, viability, and tasks performed. Using the total_task_count and/or total_task_performance_count flags will add that statistic to the output. (In the case of total_task_performance_count, this will be an average over the members of the phenotype.) +
+
DETAIL [file='detail.dat'] [format ...]
+
+ Print out all of the stats for each genotype, one per line. The + format indicates the layout of columns in the file. If the filename + specified ends in .html, html formatting will be used instead of + plain text. For the format, see the section on + Genotype Statistics below. +
+
+ DETAIL_TIMELINE [file='detail_timeline.dat'] + [time_step=100] + [max_time=100000] +
+
+ Details a time-sequence of dump files. +
+
+ DETAIL_BATCHES [file='detail_baches.dat'] + [format ...] +
+
+ Details all batches. +
+
+ DETAIL_INDEX [file] + [min_batch] [max_batch] + [format ...] +
+
+ Detail all the batches between min_batch and max_batch. +
+
+ DETAIL_AVERAGE [file="detail.dat"] + [format ...] +
+
+ Detail the current batch, but print out the average for each argument, as opposed to the + individual values for each genotype, the way DETAIL would. Arguments are the same as for DETAIL. + it takes into account the relative abundance of each genotype in the batch when calculating the + averages. +
+
+ + +

 

+

Analysis Commands

+ +

+And at last, we have the actual analysis commands that perform tests on +the data and output the results. +

+ +
+
+ ANALYZE_EPISTASIS [file='epistasis.dat'] + [num_test=(all)] +
+
+ For each genotype in the current batch, test possible + double mutatants, and single mutations composing them; print both of + individual relative fitnesses and the double mutant relative fitness. + By default all double mutants are tested. If in a hurry, specify the + number to be tested. +
+
+ MAP_TASKS [dir="phenotype/"] + [flags ...] [format ...] +
+
+ Construct a genotype-phenotype array for each genotype in the current batch. The format is + the list of stats that you want to include as columns in the array + (see Genotype Statistics for more info). Additionally you can have + special format flags; the possible flags are 'html' to print output in HTML format, and + 'link_maps' to create html links between consecutive genotypes in a lineage. The flag + 'use_manual_inputs input.1 input.2 input.3' where input.X are integers + allow for designated environmental inputs to be used when evaluating the genotype-phenotype mapping. + Manually specified environment inputs must conform to the pseudo-random numbers as + described in cEnvironment::SetupInputs. +
+
+ MAP_MUTATIONS [dir="mutations/"] + [flags ...] +
+
+ Construct a genome-mutation array for each genotype in the + current batch. The format has each line in the genome as a row + in the chart, and all available instructions representing the columns. + The cells in the chart indicate the fitness were a mutation to + occur at the position in the matrix, to the listed instruction. + If the 'html' flag is used, the charts will be output in HTML format. +
+
+ MAP_DEPTH [filename='depth_map.dat'] + [min_batch=0] [max_batch=cur_batch-1] +
+
+ This will create a depth map (like those we use for phylogeny + visualization) in the filename specified. You can direct which + batches to take this from, but by default it will work perfectly after + a LOAD_MULTI_DETAIL. +
+
+ AVERAGE_MODULATITY [file='modularity.dat'] + [task.0 task.1 task.2 task.3 task.4 task.5 + task.6 task.7 task.8] +
+
+ Calculate several modularity measuers, such as how many tasks is an + instruction involved in, number of sites required for each task, etc. + The measures are averaged over all the organisms in the current batch + that perform any tasks. For the full output list, do + AVERAGE_MODULATITY legend.dat At the moment doesn't support html + output format and works with only 1 and 2 input tasks. +
+
+ HAMMING [file="hamming.dat"] + [b1=current] [b2=b1] +
+
+ Calculate the hamming distance between batches b1 and b2. If only + one batch is given, calculations are on all pairs within that batch. +
+
+ LEVENSTEIN [file='lev.dat'] + [batch1] [b2=b1] +
+
+ Calculate the levenstein distance (edit distance) between batches b1 + and b2. This metric is similar to hamming distance, but calculates + the minimum number of single insertions, deletions, and mutations to + move from one sequence to the other. +
+
+ SPECIES [file='species.dat'] + [batch1] [batch2] + [num_recombinants] +
+
+ Calculates the percentage of non-viable recombinants between all + pairs of organisms from batches 1 and 2. Number of random recombination + events for each pair of organisms is specified by num_recombinants. + Recombination is done in the same way as in the birth chamber when + divide-sex is executed. +
Output: Batch1Name Batch2Name AveDistance Count FailCount +
+
+ RECOMBINE + [batch1] [batch2] + [batch3] [num_recombinants] +
+
+ Similar to Species command, but instead of calculating things on the spot, + just create all the recombinant genotypes using organisms from baches 1 and 2 + and put them in the batch3. +
+
+ ANALYZE_REDUNDANCY_BY_INST_FAILURE +
+
+ Determine redundancy by calculating the percentage of the lifetimes where fitness is decreased over a range of instruction failure probabilities. + +
+
+ ANALYZE_COMPLEXITY + [mut_rate] [directory] + [useResources] [batchFrequency] +
+
+ Loops through each genotype in the batch and tests the fitness of each single site mutant. useResources is a flag to set whether the testCPU should use resources when testing the mutants. Calculates probabilities at mutation selection balance, normalizes fitness values, and calculates and outputs complexity based on entropy. +
+ +
+ ANALYZE_LINEAGE_COMPLEXITY +
+
+ Loops through each genotype in the batch and calculates the number of positive and neutral mutations for single and double mutations. Calculates entropy as (log(pos_neut_mut/( pow((double)num_insts,(double)2)*(gen_length)*(gen_length-1)*(0.5))) / log(num_insts) where num_insts is the number of instructions in the instruction set. Calculates and outputs complexity as gen_length-entropy. +
+ +
+ ANALYZE_KNOCKOUTS +[file_name] [max_knockouts] +
+
+ Loops through all genomes in batch and tests the removal of each instruction (-2=lethal, -1=detrimental, 0=neutral, 1=beneficial). If max_knockouts is more than one, also tests pairs of knockouts. If both individual knockouts are both harmful, but in combination they are neutral or even beneficial, they should not count as information. If the individual knockouts are both neutral (or beneficial?), but in combination they are harmful, they are likely redundant to each other. For now, count them both as information. Outputs the counts of each type of instruction. + +
+ +
+ GET_SKELETONS +[max_knockouts=2] +
+
+ Similar to analyze_knockouts, however instead of just counting the number of non-informative sites, it removes completely non-informative (i.e. neutral) sites, and replaces sites that are informative only as placeholders with the NULL instruction. This creates genotype "skeletons". If max_knockouts is 1, it only tests single knockouts. If max_knockouts is more than 1 (default), it tests double knockouts as well (such as inc and then dec which are only neutral when removed together). (Development note: GET_SKELETONS can be called in analyze mode to skeletonize the current batch, but if you're building a more complicated command that involves skeletons, take a look at helper function with the same name that returns a vector of skeletons.) + +
+ +
+ ANALYZE_POP_COMPLEXITY +
+
+ Loops through all genotypes in batch and outputs the complexity of each genotype as 1 - entropy. + +
+ +
+ ANALYZE_NEWINFO +[mutation_rate] [directory] +
+
+ Only works for fixed length runs and requires lineage in the batch. Calculates the information of each organism and its parent about the environment and finds if there is a gain or decrease of information. Compares parent and child information at each instruction site to determine if information has been gained or lost. Calculates information the same as ANALYZE_COMPLEXITY. + +
+ +
+ ANALYZE_MUTATION_TRACEBACK +
+
+ Works best on lineages and requires fixed length genomes. Loops through each genotype to check for mutations from the previous genotype in the lineage and then tests if those mutations are currently adaptive. Prints out the number of beneficial, neutral, detrimental and static sites at the given lineage depth. + +
+ +
+ ANALYZE_COMPLEXITY_DELTA +
+
+ This command will examine the current population, and sample mutations to see what the distribution of complexity changes is. Only genotypes with a certain abundance (default=3) will be tested to make sure that the organism didn't already have hidden complexity due to a downward step. + +
+ +
+ +

 

+

Building Input Files for Avida

+ +

+These commands build input files for Avida, using the capabilities of analyze mode to +automate some tedium. +

+ +
+
+ WRITE_CLONE [file='clone.dat'] + [num_cells=-1] +
+
+ Creates a clone population file (as SaveClone) + from the current batch, suitable for loading with LoadClone. + The starting update is 0 and the archive is empty. num_cells should be the number + of cells in the world -- the default value of -1 will not be accepted by LoadClone, + so be sure to specify the correct number. +
+ Warning: Unlike SaveClone, WRITE_CLONE does not preserve location. + Any spatial structure the population had is lost. +
+
+ WRITE_INJECT_EVENTS [file='events_inj.cfg'] + [start_cell=0] [lineage=0] +
+
+ Creates an events file which injects all the genotypes of the current + batch at update 0. Injection starts at the given start_cell id and increments + upward. All injected organisms are assigned the given lineage label and start + with the relevant merit; num_cpus copies of each genotype are injected. +
+ Warning: injection is in order that the genotypes appear in the batch. + This will break any spatial structure your population may have had. +
+
+ WRITE_INJECT_INITIAL [file='events_inj.cfg'] + [start_cell=0] [lineage=0] +
+
+ Creates an events file which injects all the genotypes of the current + batch before update 0 (same as WRITE_INJECT_EVENTS but doesn't cause no organism errors). Injection starts at 0 (this is made for reintroduction of single organisms only!) and injects a single organism only. Injected organism is assigned the given lineage label and starts + with the relevant merit. +
+ Warning: injection is in order that the genotypes appear in the batch and doesn't take into account the original location. + This will break any spatial structure your population may have had. +
+ +
+ WRITE_COMPETITION [join_UD=0] + [start_merit=50000] [file='events_comp.cfg'] + [batch_A=cur_batch-1] + [file=batch_B=cur_batch] [grid_side=-1] + [lineage=0] +
+
+ Creates an events file which acts much like the one produced + by WRITE_INJECT_EVENTS, but injects two populations (from the given batches), separates + the populations at update 0 (via SeverGridRow grid_side), and joins them at the given + join_UD. Organisms from batch_A are injected starting at cell id 0; organisms from + batch_B are injected starting at cell id grid_side*grid_side. (If grid_side is negative, + an attempt will be made to infer it from the number of organisms in the population.) +
+ Each population should be square, of grid_side x grid_side dimensions. (You will have + to set up the world in avida.cfg to have WORLD_X of grid_side and WORLD_Y of 2*grid_side.) + Each population may not be larger than 10,000 organisms. Organisms from batch_A will + be assigned the given lineage label; organisms from batch_B will be assigned the given + lineage label + 1. +
+ Warning: Like WRITE_INJECT_EVENTS, WRITE_COMPEITITIONS will destroy any + spatial structure the populations may have had. Also, since it severs/joins only the grid_side + row, it is not suitable for use with WORLD_GEOMETRY values other than 1 (bounded grid). +
+
+ + +

 

+

Using Test CPU Resources Summary

+ +

+This summary is given to help explain the use and constraints for using resources. +

+

+When a command specifies the use of resources for the test cpu, it should not +affect the state of the test cpu after the command has finished. However, this +means that the test cpu is no longer guaranteed to be reentrant. Each command +will set up the environment and the resource count in the test cpu with it's own +environment and resource count. When the command has finished it will set the the +test cpu's environment and resource count back to what they were before the command +was executed. +

+

+Resource usage for the test cpu occurs by setting the environment and then +setting up the resource count using the environment. Once the resource +count has been set up, it will not change during the use of the test cpu. +When an organism performs and IO, completing a task, the concentrations are +not changed. This was a design decision, but is easily changed. +

+

+In analyze, a new data structure was included which contains a time ordered +list of resource concentrations. This list can be used to set up resources +from different time points. By using the update parameter in the RECALCULATE (or RECALC) function, +you can use the resource concentrations from a specified time +point. If the LOAD_RESOURCES command is not called, the list defaults to +a single entry which is the the initial concentrations of the resources +specified in the environment configuration file. +

+ +
+
PRINT_TEST_CPU_RESOURCES
+
+ This command first prints the whether or not the test cpu is using + resources. Then it will print the concentration for each resource. +
+
LOAD_RESOURCES [file_name="resource.dat"][ class="cmdargopt">resource_cpu_cycle_offset=0]
+
+ This command loads a time oriented list of resource concentrations. + The command takes a file name containing this type of data, and + defaults to resource.dat. The format of the file must be the same + as resource.dat, and each line must be in the correct chronological + order with oldest first. + The resource_cpu_cycle_offset parameter will influence which update RECALCULATE, + etc. will use from the resource.dat file. Specifically, the update specified + in RECALCULATE, etc. will have resource_cpu_cycle_offset / AVE_TIME_SLICE + (integer division) added to it. Unless you know exactly why you would use this + option, you should leave it at its default of 0. +
+
+ + + +

 

+

Genotype Statistics

+ +

+ Avida analyze mode recognizes several keywords that correspond to information about genotypes. + Several commands (such as DETAIL and MAP) require the use of these as format parameters + to specify what genotypic features should be output. Others (such as FILTER) use them to identify + specific genotypes that possess certain qualities. Before these commands are used, other + processing functions may need to be run. +

+

+Allowable formats after a normal load (assuming these values were available +from the input file to be loaded in) are: +

+
+ + + + + + + + + + + + + + + + + + + + + +
id (Genome ID)parent_id (Parent ID)parent2_id (Second Parent ID in sexual genotypes)
num_cpus (Number of CPUs)total_cpus (Total CPUs Ever)length (Genome Length)
update_born (Update Born)update_dead (Update Dead)depth (Tree Depth)
lineage (Unique Lineage Label)sequence (Genome Sequence)task_list (List of all tasks performed)
+
+ +

+After a RECALCULATE (or RECALC), these additional formats become available: +

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
viable (Is Viable [0/1])copy_length (Copied Length)exe_length (Executed Length)
merit (Merit)comp_merit (Computational Merit)gest_time (Gestation Time)
efficiency (Replication Efficiency)fitness (Fitness)div_type (Divide type used; 1 is default)
mate_id (Mate Selection ID Number + (sexual genotypes))executed_flags (Executed Flags)task_order (Task Performance Order)
task.n (# of times task number n is done)task.n:binary (is task n done, 0/1)total_task_count (# of unique tasks done)
total_task_performance_count (total # of tasks done)inst.n (# of times instruction #n is done)r_tot.n (amount of resource n added to the organism's store in its lifetime)
r_avail.n (amount of resource n in organism's store)r_spec.n (# of times specification #n is used)
+
+ +

+It gives a count of 0 if there is no such instruction. +

+ +

+A note on r_spec.n: This counts nop specifications done by any and all "collect-type" instructions -- that is, any instruction that uses the helper function DoCollect. If more than one such instruction is included in the instruction set, r_spec.n will include specification counts for both instructions without any differentiation. +For details on what the specification numbers mean, see cCodeLabel::AsIntUnique. +

+ +

+If a FIND_LINEAGE was done before the RECALCULATE (or RECALC), the parent +genotype for each regular genotype will be available, enabling the +additional formats: +

+ +
+ + + + + + + + + + + + + + + + +
parent_dist (Parent Distance)ancestor_dist (Ancestor Distance)
comp_merit_ratio, (Computational Merit Ratio with parent)efficiency_ratio (Replication Efficiency Ratio with parent)
fitness_ratio (Fitness Ratio with parent)parent_muts (Mutations from Parent)
html.sequence (Genome Sequence in Color; html format)
+
+ +

+If an ALIGN is run, one additional format is available: +

+ +
+ + + + +
alignment (Aligned Sequence)
+
+ +

+If a RECALCULATE (or RECALC) was done before the ALIGN, the following format is available: +

+ +
+ + + + +
alignment_executed_flags (Alignment Executed Flags)
+
+ +

+If tags have been applied to genotypes in analyze mode, an additional format +is available: +

+ +
+ + + + +
tag (Genotype Tag)
+
+ +

+There are a handful of commands that will automatically perform +landscapping. The landscape will only be run once per organism even when +multiple output variables are used. For enhanced performance on +multi-processor/multi-core systems, see the +PrecalcLandscape action. +

+ +
+ + + + + + + + + + + + + +
frac_dead (Fraction of Lethal Mutations)frac_neg (Fraction of Harmful Mutations)
frac_neut (Fraction of Neutral Mutations)frac_pos (Fraction of Beneficial Mutations)
complexity (Physical Complexity of Organism)land_fitness (Average Mutation Fitness)
+
+ +

+Phenotypic plasticity information is available through a number +of different commands. This information will be gathered in one +of two manners. If RECALC num_trials X is called, where X is greater +than 1, phenotypic plasticity information for each genotype in the +batch will be collected. If RECALC is not called or is called with +with just one trial (the default for RECALC), then using these commands will request 1000 +trials for each genotype to gather plasticity information. Requesting an analysis +of phenotypic plasticity in this manner will not re-evaluate other genotype statistics. +

+

+ + + + + + + + + + + + + + + + + + + + + + + + + +
num_phen (Number of Phenotypes Identified)phen_avg_fitness (Weighted Average Fitness)
num_trials (Number of Phenotype Tests)phen_entropy (Phenotypic Entropy [bits])
phen_max_fit_freq (Maximum Fitness Phenotype Frequency)phen_max_fitness (Maximum Phenotype Fitness)
phen_min_fit_freq (Minimum Fitness Phenotype Frequency)phen_min_fitness (Minimum Phenotype Fitness)
phen_likely_freq (Most Likely Phenotype Frequency)phen_likely_fitness (Fitness of the Most Likely Phenotype)
prob_task.n (Probability of task n being performed) prob_viable (Probability of genotype viability)
+
+ +

Variables

+ +

+For the moment, all variables can only be a single character (letter or +number) and begin with a $ whenever they need to be translated to their +value. Lowercase letters are global variables, capital letters are +local to a function (described later), and numbers are arguments to a +function. A $$ will act as a single dollar sign, if needed. +

+ +
+
SET [variable] [value]
+
+ Sets the variable to the value... +
+
CONFIG_GET [config variable] [variable]
+
+ Retrieves the value of the supplied configuration variable and places it into the supplied analyze mode variable. + For example, 'CONFIG_GET RANDOM_SEED r' will place the value of the random number seed (as specified in the + configuration settings) into the variable r. +
+
CONFIG_SET [config variable] [value]
+
+ Sets the supplied configuration variable to the value specified with the command. +
+
+ FOREACH [variable] [value] + [value ...] +
+
+ Set the variable to each of the values listed, and run the code that + follows between here and the next END command once for each of + those values. +
+
+ FORRANGE [variable] [min_value] + [max_value] [step_value=1] +
+
+ Set the variable to each of the values between min and max (at steps + given), and run the code that follows between here and the next END + command, once for each of those values. +
+
+ + +

 

+

Functions

+ +

+These functions are currently very primitive with fixed inputs of +$0 through $9. $0 is always the function name, and then there can be up +to 9 other arguments passed through. Once a function is created, it can +be run just like any other command. +

+ +
+
FUNCTION [name]
+
+ This will create a function of the given name, including in it all + of the commands up until an END is found. These commands will be + bound to the function, but are not executed until the function is + run as a command. Inside the function, the variables $1 through $9 + can be used to access arguments passed in. +
+
+ +

+Currently there are no conditionals or mathematical commands in this +scripting language. These are both planned for the future. +

\ No newline at end of file diff --git a/docs/documentation/Analyze-mode-:-building-your-own-commands.md b/docs/documentation/Analyze-mode-:-building-your-own-commands.md new file mode 100644 index 0000000..0b7c802 --- /dev/null +++ b/docs/documentation/Analyze-mode-:-building-your-own-commands.md @@ -0,0 +1,29 @@ +One really useful feature in analyze mode is the ability for the user to construct a variety of their own commands without modifying the source code. This is done with the FUNCTION command. For example, if you know you will always need a file called lineage.html with very specific information in it, you might write a helper command for yourself as follows: + +
+  FUNCTION MY_HTML_LINEAGE  # arg1=run_directory
+    PURGE_BATCH
+    LOAD $1/detail-100000.spop
+    FIND_LINEAGE num_cpus
+    RECALCULATE
+    DETAIL $1/lineage.html depth parent_dist length fitness html.sequence
+  END
+
+ +This works identically to how we found lineages and printed their data in the section above. Only this time, it has created the new command called MY_HTML_LINEAGE that you can use anytime thereafter. Arguments to functions work similar to variables, but they are numbers instead of letters. Thus $1 translates to the first arguments, $2 becomes the second, and so on. You are limited to 9 arguments at this point, but that should be enough for most tasks. $0 is the name of the function you are running, in case you ever need to use that. + +You may be interested in also using functions in conjunction with the SYSTEM command. Anything you type as arguments to this command gets run on the command line, so you can make functions to do anything that could otherwise be done were you at the shell prompt. For example, imagine that you were going to use a lot of compressed files in your analysis that you would first need to uncompress. You might right a function like: + +
+  FUNCTION UNZIP   # Arg1=filename
+    SYSTEM gunzip $1
+  END
+
+ +This is a shorter example than you might typically want to write a function for, but it does get the point across. This would allow you to just type UNZIP whenever you needed to uncompress something. + +Functions are particularly useful in conjunction with the INCLUDE command. You can create a file called something like my_functions.cfg in your Avida work directory, define a bunch of functions there, and then start all of your analyze.cfg files with the line: + + INCLUDE my_functions.cfg + +and you will have access to all of your functions thereafter. Ideally, as this language becomes more flexible, so will your ability to create functions within the language, so you will be able to develop flexible and useful libraries for yourself. diff --git a/docs/documentation/Analyze-mode-:-finding-lineages.md b/docs/documentation/Analyze-mode-:-finding-lineages.md new file mode 100644 index 0000000..1792c3d --- /dev/null +++ b/docs/documentation/Analyze-mode-:-finding-lineages.md @@ -0,0 +1,18 @@ +Quite often, the portion of an Avida run that we will be most interested in is the lineage from the final dominant genotype back to the original ancestor. As such, there are tools in Avida to get at this information. + +
+  FORRANGE i 100 199
+    SET d /home/charles/dev/avida/runs/evo-neut/evo_neut_$i
+    PURGE_BATCH
+    LOAD $d/detail-100000.spop
+    FIND_LINEAGE num_cpus
+    RECALCULATE
+    DETAIL lineage.$i.html depth parent_dist length fitness html.sequence
+  END
+
+ +This program looks very similar to one in the Using Variables example. The first four lines are actually identical. A .spop detail file contains all of the genotypes that were currently alive in the population at the time it was printed, and by default all of the genotypes that are direct ancestors of those that were still alive. (If you used the save_historic=1 option when you saved this population, the .spop contains only the currently-alive genomes, and you will not find much of a lineage!) + +The .spop file therefore gives us the lineages of the entire population back to the original ancestor. Since we are only interested in a single lineage, the next thing we do is run the FIND_LINEAGE command to pick out a single genotype, and discard everything else except for its lineage. In this case, we pick the genotype with the highest abundance (the most virtual CPUs associated with it) at the time of printing. + +As before, the RECALCULATE command gets us any additional information we may need about the genotypes, and then we print that information to a file using the DETAIL command. The filenames that we are using this time have the format lineage.$i.html, so they are all being written to the current directory with filenames that incorporate the run number right in them. Also, because the filename ends in the suffix '.html', Avida knows to print the file in a proper html format. Note that the specific values that we choose to print take advantage of the fact that we have a lineage (and hence measured things like the genetic distance to the parent) and are in html mode (and thus can print the sequence using colors to specify where exactly mutations occurred). diff --git a/docs/documentation/Analyze-mode-:-testing-a-genome-sequence.md b/docs/documentation/Analyze-mode-:-testing-a-genome-sequence.md new file mode 100644 index 0000000..4e22e07 --- /dev/null +++ b/docs/documentation/Analyze-mode-:-testing-a-genome-sequence.md @@ -0,0 +1,14 @@ +The following program will load in a genome sequence, run it through a test CPU, and output the information about it in a couple of formats. + +
+  VERBOSE
+  LOAD_SEQUENCE rmzavcgmciqqptqpqcpctletncogcbeamqdtqcptipqfpgqxutycuastttva
+  RECALCULATE
+  DETAIL detail_test.dat fitness merit gest_time length viable sequence
+  TRACE
+  PRINT
+
+ +This program starts off with the VERBOSE command so that Avida will print to the screen all of the details about what is going on as it runs the analyze script; I recommend you begin all of your programs this way for debugging purposes. The program then uses the LOAD_SEQUENCE command to allow the user to enter a specific genome sequence in its compressed format. This will translate the genome into the proper genotype as long as you are using the correct instruction set file, since that file determines the mappings of letters to instructions). + +The RECALCULATE command places the genome sequence into a test CPU, and determines its fitness, merit, gestation time, etc. so that the DETAIL command that follows it can have access to all of this information as it prints it to the file "detail_test.dat" (its first argument). The TRACE and PRINT commands will then print individual files about this genome, the first tracing its execution line-by-line, and the second summarizing all sorts of statistics about it and displaying the genome. Since no directory was specified for these commands, archive/ is assumed, and the filenames are org-S1.trace and org-S1.gen. If a genotype has a name when it is loaded, that name will be kept, but if it doesn't, it will be assigned a name starting at org-S1, then org-S2, and so on counting higher. The TRACE and PRINT commands add their own suffixes to the genome's name to determine the filename they will be printed as. diff --git a/docs/documentation/Analyze-mode-:-try-it-yourself-exercises.md b/docs/documentation/Analyze-mode-:-try-it-yourself-exercises.md new file mode 100644 index 0000000..d59099f --- /dev/null +++ b/docs/documentation/Analyze-mode-:-try-it-yourself-exercises.md @@ -0,0 +1,12 @@ +Here are a couple of example problems you can try to see how well you can use analyze mode. These should get you used to working with it for future projects. + +Problem 1. A detail file in Avida contains one line associated with each genotype, in order from the most abundant to the least. Currently, the LOAD command will load the entire file's worth of genotypes into the current batch, but what if you only wanted the top few? You should write a function called LOAD_DETAIL_TOP that takes two arguments. The first ($1) is the name file that needs to be loaded in (just as in the original command), and the second is the number of lines you want to load. + +The easiest way to go about doing this is by using the SYSTEM command along with the Unix command head which will output the very top of a file. If you typed the line: + + head -42 detail-1000.spop > my_temp_file + + +The file my_temp_file would be created, and its contents would be the first 42 lines of detail-1000.spop. So, what you need this function to do is create a temporary file with proper number of lines from the detail file in it, load that temp file into the current batch, and then delete the file (using the rm command). Warning: be very careful with the automated deletions -- you don't want to accidentally remove something that you really need! I recommend that you use the command rm -i until you finish debugging. This problem may end up being a little tricky for you, but you should be able to work your way through it. + +Problem 2. Now that you have a working LOAD_DETAIL_TOP command, you can run LOAD_DETAIL_TOP 1 in order to only load the most dominant genotype from the detail file. Rewrite the example program from the section "Working with Batches" above such that you now only need to work within a single batch. diff --git a/docs/documentation/Analyze-mode-:-using-variables.md b/docs/documentation/Analyze-mode-:-using-variables.md new file mode 100644 index 0000000..734647e --- /dev/null +++ b/docs/documentation/Analyze-mode-:-using-variables.md @@ -0,0 +1,25 @@ +Often, you will want to run the same section of analyze code with multiple different inputs each time through, or else you might simply want a single value to be easy to change throughout the code. To facilitate such programming practices, variables are available in analyze mode that can be altered for each repitition through the code. + +There are actually several types of variables, all of which are a single letter of number. For a command that requires a variable name as an input, you simply put that variable where it is requested. For example, if you were going to set the variable i to be equal to the number 12, you would type: + + SET i 12 + +But later on in the code, how does Avida know when you type an i if you really want the letter 'i' there, or if you prefer the number 12 to be there? To distinguish these cases, you must put a dollar sign '$' before a variable wherever you want it to be translated to its value instead of just using the variable name itself. + +There are a few different commands that allow you to manipulate a variable's value, and sometimes execute a section of code multiple times based off of each of the possible values. Here is one example: + +
+  FORRANGE i 100 199
+    SET d /home/charles/dev/avida/runs/evo-neut/evo_neut_$i
+    PURGE_BATCH
+    LOAD $d/detail-100000.spop
+    RECALCULATE
+    DETAIL $d/detail.dat update length fitness sequence
+  END
+
+ +The FORRANGE command runs the contents of the loop once for each possible value in the range, setting the variable i to each of these values in turn. Thus the first time through the loop, 'i' will be equal to the value '100', then '101', '102', all the way up to '199'. In this particular case, we have 100 runs (numbered 100 through 199) that we want to work with. + +The first thing we do once we're inside the loop is set the value of the variable 'd' to be the name of the directory we're going to be working with. Since this is a long directory name, we don't want to have to type it over every time we need it. If we set it to the variable d, then all we need to do is type '$d' in the future, and it will be translated to the full name. Note that in this case we are setting a variable to a string instead of a number; that's just fine and Avida will figure out how to handle it properly. This directory we are working with will change each time through the loop, and that it is no problem to use one variable as part of setting another. + +After we know what directory we are using, we run a PURGE_BATCH to get rid of all of the genotypes from the last time through the loop (lest we just keep building up more and more genotypes in the current batch) and then we refill the batch by using LOAD to load in all of the genotypes saved in the file detail-100000.spop within our chosen directory. The RECALCULATE command runs all of the genotypes through a test CPU so we have all the statistics we need, and finally DETAIL will print out the stats we want to the file detail.dat, again placing it in the proper directory. The END command signifies the end of the FORRANGE loop. diff --git a/docs/documentation/Analyze-mode-:-working-with-batches.md b/docs/documentation/Analyze-mode-:-working-with-batches.md new file mode 100644 index 0000000..b89ee21 --- /dev/null +++ b/docs/documentation/Analyze-mode-:-working-with-batches.md @@ -0,0 +1,17 @@ +In analyze mode, we can load genotypes into multiple batches and we then operate on a single batch at a time. So, for example, if we wanted to only consider the dominant genotypes at time points 100 updates apart, but all we had to work with were the detail files (containing all genotypes at each time point) we might write a program like: + +
+  SET d /home/charles/avida/runs/mydir/here-it-is
+  SET_BATCH 0
+  FORRANGE u 100 100000 100            # Cycle through updates
+    PURGE_BATCH                        # Purge current batch (0)
+    LOAD $d/detail-$u.spop  # Load in the population at this update
+    FIND_GENOTYPE num_cpus             # Remove all but most abundant genotype
+    DUPLICATE 0 1                      # Duplicate batch 0 into batch 1
+  END
+  SET_BATCH 1                          # Switch to batch 1
+  RECALCULATE                          # Recalculate statistics...
+  DETAIL dom.dat fitness sequence      # Print info for all dominants!
+
+ +This program is slightly more complicated than the other examples, so I added in comments directly inside it. Basically, what we do here is use batch 0 as our staging area where we load the full detail dumps, strip them down to only the single most abundant genotype, and then copy that genotype over into batch 1. By the time we're done, we have all of the dominant genotypes inside of batch 1, so we can print anything we need right from there. diff --git a/docs/documentation/Avida-3-API.md b/docs/documentation/Avida-3-API.md new file mode 100644 index 0000000..47bb9c2 --- /dev/null +++ b/docs/documentation/Avida-3-API.md @@ -0,0 +1,273 @@ +Avida 3 will include and be built around a flexible, extensible application programming interface (API). The intention of the API is to provide a powerful, stable interface to core Avida functionality. + +The API will be broken up into multiple modules that will be connected together to create rich experiments and powerful analyses. The development of this API is very active right now. The following provides an overview of existing components and an estimation of their completeness and stability. + +### API Modules +* core +* data +* environment +* systematics +* util +* viewer + +### Notes +The following are miscellaneous notes, which may or may not be relevant to the current Avida 3.0 plans. Preserved for consideration. + +* Get rid of merit. Organisms have energy (which they absorb by performing reactions) and metabolic rate, which determines how quickly they use that energy to execute instructions. +* Each thread in an organism is placed into the scheduler. When a thread is created, the scheduler assigns it a process ID, and that ID is then freed up with the thread is removed. A thread must keep track of its own ID. When a thread is removed, its ID is placed in a container of free IDs. Only when that container is empty are new IDs created. This will happen rarely enough that its okay if its a slow process. +* New analyze mode! This should be interesting... Require lex & yacc? +* Implement new method of performing mutations. The old stuff should be entirely removed. +* This version will be optimized for stack-based CPUs, but the old register based CPUs should still function fine. +* Make sure all output files have headers. There should be a central object that all files are output through that will make sure this is the case. +* Make events just call analyze scripts. Re-design entire event structure. + +### Mutations.cfg ideas +
+# @CAO : THIS IS A PROTOTYPE FILE FOR HOW I'D LIKE TO SEE MUTATIONS WORK
+
+# This file is used to configure the mutations that occur during an avida
+# run.  The format is simple:
+#
+#   MUTATION     
+#
+# The "trigger" determines when the mutation should be tested for. 
+# Possibilities are -
+#
+#   update  : Test for these mutations each update
+#   divide  : Test during the successful birth of an offspring
+#   parent  : Test on a parent during a divide operation
+#   write   : Test each time an instruction is written to memory
+#   read    : Test whenever an instruction is read from memory.
+#   exec    : Test while an instruction is being processed by the hardware
+#
+# A copy command will perform both a read and a write.  A read mutation will
+# affect the site being read, and are therefore particulaly dangerous.
+#
+# The scope of a mutation type determines how much will be mutated.  There
+# are currently a few options -
+#
+#   genome  : A single mutation occurs in the whole genome.
+#   local   : Mutations occur at a local position.  If no local position can
+#             be specified in the trigger (i.e. 'parent') nothing happens.
+#   prop    : Proportional: same as local, but the rate used is normalized to
+#             1/genome_length
+#   global  : Same as local, but *all* positions in the genome are tested.
+#   spread  : Same as prop, but all positions are tested.
+#
+# The type of mutation determines what happens when a mutation does occur
+# at a site -
+#
+#   point    : Change the affected locus to a random instruction.
+#   insert   : Insert a random instruction at this poistion.
+#   delete   : Remove the instruction currently at this position.
+#   head_inc : Advance heads at this position.
+#   head_dec : Retreat heads at this position.
+#   temp     : Don't change the genome, but temporarily act as if a change has
+#              occured.  This is only relevent for types "read" and "exec".
+#   kill     : Sterilize the organism affected so that it is effectively dead.
+#
+# Finally, the rate indicates the frequency at which mutations occur.
+#
+# EXAMPLES:
+#
+# Old stype copy mutation rate of 0.0075:
+#
+#   MUTATION copy_mutation write local point 0.0075
+#
+# Old style divide insertion of 0.05:
+#
+#   MUTATION divide_ins divide genome insert 0.05
+#
+# Keeping an average genome mutation rate at 2.0 with copy mutations...
+#
+#   MUTATION copy_spread write prop point 2.0
+#
+# Most types of mutations that people want should be possible.
+#
+# CONFLICTS:
+#  Only local & spread scopes can interact with head/temp types.
+#  Divide trigger cannot work with local & spread scopes.
+
+ + +### Stack-based Instruction Set +
+# This new CPU has 8 heads, 2 of each main type, and otherwise has four
+# stacks (A, B, C, and D) and no registers.
+
+# Base Instruction Set
+# Nops (1-4)
+Nop-A      1   # Associated with the Instruction Pointers
+Nop-B      1   # Associated with the Read Heads
+Nop-C      1   # Associated with the Write Heads
+Nop-D      1   # Associated with the Flow Heads
+
+# Other control functions (5)
+Toggle     1  # Causes all instructions to swap to a complementary behavior
+              # affects only the instruction that immediately follows it.
+              # A nop indicates that the associate head should be toggled
+              # to its alternate.  Two toggles will reset all toggled states
+
+# Single input Math -- *modifies* top of ?Stack-B? (6-7)
+Val-Shift  1  # shirt-r before toggle, shift-l after.
+Val-Inc    1  # inc before toggle, dec after
+
+# Double input math -- uses top of Stack-A and Stack-B; pushes result onto
+# the top of Stack-B (8-9)
+Val-Nand   1  # unaffected by toggle
+Val-Add    1  # add before toggle, sub after
+
+# Biological  (10-13)
+SetMemory  1  # Set the write head at the beginning of a memory space.  Up
+              #   to four memory spaces can be used at once.  Nop-A is the
+              #   main genome, and the other nops are possible offspring.
+              #   A nop argument will indicate a space; no nops will find
+              #   an "unclaimed" memory space (if possible)
+              #   Perhaps Toggle can be used for recombination somehow??
+Divide     1  # Divide off offspring memory.  After toggle becomes Inject.
+              #   If threads are active a successful inject will also cause
+              #   a fork.  In either case, it uses the memory that contains
+              #   the active write head.
+Inst-Read  1  # Push the instruction at ?read-head? into Stack-A (advance 
+              #   head) Toggle to move head back by one rather than advance.
+Inst-Write 1  # Pop Stack-A into position at ?write-head? (advance head)
+              #   Toggle to move head back by one rather than advance.
+
+# Flow Control (14-15)
+If-Equal   1  # Compares top of ?Stack-A? with successor (Default: Stack-B)
+              #   Becomes If-NEqual after toggle
+If-Less    1  # Compares top of ?Stack-A? with successor (Default: Stack-B)
+              #   Becomes If-Greater after toggle
+
+# Head Control (16-19)
+Head-Push  1  # Push position of ?IP? head onto Stack-B.
+              #   Toggle to use Stack-D
+Head-Pop   1  # Move ?flow-head? to address in Stack-B (pop Stack-B)
+              #   Toggle to use Stack-D
+
+Head-Move  1  # Move ?IP? head to flow-head
+              #   - if flow-head is given as nop, advance flow-head
+              #   Toggle to decrement flow-head when given as nop.
+Search     1  # Search for matching template, set flow head to last line,
+              #   template size to Stack-A and template distance to Stack-B
+	         #   If no template, move flow-head to next line, set A&B=0.
+              #   Toggle to NOT leave size&distance
+
+# Stack Control (20-24)
+Push-Next  1   # Pop off ?Stack-A? and push on successor   (Default: Stack-B)
+Push-Prev  1   # Pop off ?Stack-B? and push on predecessor (Default: Stack-A)
+Push-Comp  1   # Pop off ?Stack-B? and push on complement  (Default: Stack-D)
+Val-Delete 1   # Pop off (and lose) top value of ?Stack-B?
+Val-Copy   1   # Duplicate the contents at the top of ?Stack-B?
+
+# CPU:
+#  Stack-A (Used in copying & math)
+#  Stack-B (Used for positioning and math)
+#  Stack-C (Input)      -- Filled on birth
+#  Stack-D (Output)     -- Scanned (and emptied) on divide
+#
+# Four nops.  Each nop has a predecessor, successor and complement (opposite)
+#
+#  nop-A -> IP
+#  nop-B -> Read Head
+#  nop-C -> Write Head
+#  nop-D -> Flow Head
+#
+# Note lack of allocate instruction!
+# The organism has additional memory space that the write heads starts out
+# at the beginning of.  It is treated as an extension of the main memory,
+# BUT is local to each thread if there is more than one.
+
+# SAMPLE ORGANISM:
+#
+# Search       #  1:  Find organism end.
+# Nop-C        #  2:  - Match A:A
+# Nop-C        #  3:
+# Head-Push    #  4:  Save end position to Stack-B
+# Nop-D        #  5:  - Flow head is at end...
+# Push-Prev    #  6:  Move end position to Stack-A
+# SetMemory    #  7:  Place write-head in memory space for offspring
+# Search       #  8:  Drop flow head at start of copy loop
+# Inst-Read    #  9:
+# Inst-Write   # 10: 
+# Head-Push    # 11:  Get current position of...
+# Nop-C        # 12:  - Read-Head
+# If-Equal     # 13:  Test if we are done copying...
+# Divide       # 14:  ...If so, divide.
+# Head-Move    # 15:  ...If not, continue with loop.
+# Nop-A        # 16:
+# Nop-A        # 17:
+
+# Other possible, special instructions...
+# ScanWorld  1   # Environment-specific scanning instruction...
+# Val-Swap   1   # Swap top contents of ?Stack-A? with successor (Default: B)
+                 #  Toggle will swap with complement.
+# Inst-Copy  1   # Combine read and write
+# Inst-Move  1   # Like Inst-Copy, but actually deletes original and can
+                 #   move multiple lines at once (as indicated by ?Stack-B?)
+# SearchOut  1   # Like search, but in faced creature.  Needs exact match!
+# Rotate     1   # Rotate to neighbor with template (toggle reverses dir)
+                 #   in mass action, find randomly in population.
+# If-Bit-1   1   # Is last bit of ?Stack-B? a one? (toggle to If-Bit-0)
+# If-Zero    1   # Toggle to If-N-Zero
+# If-InstEqu 1   # Does contents of ?read-head? match successor (write-head)
+                 #   (toggle to If-InstNEqu)
+# Order      1   # Put top two numbers in ?Stack-B? into numerical order
+# Push-Zero  1   # Push a zero onto the top of ?Stack-B?
+# Replicate  1   # Make a full offspring
+
+ 
+# ------- THREADING --------
+# There can only be up to four threads in an organism, specified as
+# Thead-A through Thread-D
+
+# Hardware:
+#  For threads, Stacks A and B are local, while C and D are global.
+#  All heads are local to each thread.
+#   - Read and Flow heads will initialize to fork.
+#   - Write head will initialize on new offspring memory.
+#  Each thread has its own offspring memory.
+#  Each thread keeps its own list of toggled instructions.
+
+# Instructions:
+#  ThreadFork 1   # Create a new thread.  By default this will be the next
+                  #   available thread ID, but if a nop follows it will
+                  #   indicate the thread instead.  If a thread is specified
+                  #   that already exists, its priority will increase to a
+                  #   maximum.  On the original thread executes the next
+                  #   instruction.  Toggle to ThreadKill ?cur-Thread?, which
+                  #   will decrement a thread one step, to a min of 0.
+#  If-Thread  1   # Only execute next instruction if this is ?Thread-A?
+                  #   Toggle to IfNThread
+#  ThreadCopy 1   # Make this thread an exact copy of ?Thread A? including
+                  #   working on the same memory space.  Toggle to ThreadClr
+                  #   which will reset the specifed thread (default current)
+
+# SAMPLE PARASITE
+#
+# Nop-A        #  1: Some nop to extend the template above
+# Toggle       #  2: Toggle the Divide command...
+#  Divide      #  3:   ... to become "Inject"
+# Toggle       #  4: Toggle the If-Equal command...
+#  If-Equal    #  5:   ... to become "If-NEqual"
+# Search       #  6: Locate the end, so we know when to stop.
+# Nop-C        #  7:
+# Nop-D        #  8:
+# Head-Push    #  9: Save the location of the flow head to mark the end.
+# Nop-D        # 10:
+# Push-Prev    # 11:  Move end position to Stack-A
+# SetMemory    # 12:  Claim and empty memory space
+# Search       # 13:  Drop flow head at start of copy loop
+# Inst-Read    # 14:
+# Inst-Write   # 15: 
+# Head-Push    # 16:  Get current position of...
+# Nop-C        # 17:  - Read-Head
+# If-Equal     # 18:  Test if we are done copying... (If-NEqual)
+# Head-Move    # 19:  ...If not, continue with loop.
+# Divide       # 20:  ...If so, Inject!
+# Nop-C        # 21:     ... Into the very end of the host.
+# Nop-C        # 22
+# Head-Move    # 23: Go to the beginning of the copy loop and start over!
+# Nop-A        # 24: End Template
+# Nop-B        # 25:
+
\ No newline at end of file diff --git a/docs/documentation/Avida.cfg.mediawiki b/docs/documentation/Avida.cfg.mediawiki new file mode 100644 index 0000000..cc566b2 --- /dev/null +++ b/docs/documentation/Avida.cfg.mediawiki @@ -0,0 +1,19 @@ +The Avida configuration file (avida.cfg) is the main configuration file for Avida. With this file, the user can setup all of the basic conditions for a run. + +avida.cfg is actually an excellent guide to itself; every option has a description of what it does and what its options are, and many of these pages will simply refer you to the file itself instead of replicating that description. We endeavor here to give extended explanations of particularly common or confusing options, and of settings that interact with other settings. + + +== Configuration Sections == +* [[General Settings]] +* [[Mutation Settings]] +* [[Topology Settings]] : the shape and connectedness of the world +* [[File Settings]] : other configuration files and where to save your data +* [[Instruction Set]] +* [[Reproduction Settings]] : birth and death +* [[Time Slicing Settings]] : how CPU time is distributed among organisms +* [[HTML Output Color Settings]] +* [[Resource Hoarding Settings]] : internal resource storage for organisms +* [[Divide Settings]] : limitations on organism division +* [[Settings for Genealogy Info in the Test CPU]] +* [[Mutations Reversion Settings]] +* [[Analysis Settings]]: threads and variables in analyze mode diff --git a/docs/documentation/Beginner-Documentation.md b/docs/documentation/Beginner-Documentation.md new file mode 100644 index 0000000..03ff7ed --- /dev/null +++ b/docs/documentation/Beginner-Documentation.md @@ -0,0 +1,211 @@ +# Avida: Beginner User Documentation + +As you’re beginning to use Avida to answer research questions, it can be easy to get lost in the extensive amount of variables and settings you can use in Avida. The purpose of this documentation is to identify the features that are most important for you to consider before running an experiment in Avida. For each feature, this documentation will explain what it controls, what options you have, and how and where you set those options. + +## **1. Set up the environment.** +_Why you need to do this_ + +Setting up the environment tells Avida how big your universe is and what shape you want your universe to take. This will be important in determining a) the population cap for your experiment, b) how much (if any) empty space exists in your world, and c) how proportionally (or not) the organisms in your experiment have access to other organisms and resources. What you choose in this portion of the experiment will affect how organisms in your Avida universe interact with each other and, indirectly, the carrying capacity of your Avida universe. + +_What you can do_ + +Avida allows you to customize both the world size and the world geometry. The world size determines the carrying capacity of your Avida world. In Avida (which is based on a grid system), each grid block can be occupied by only one Avida organism. So if you set the Avida grid height to 120 and the Avida grid width to 120, your Avida universe would have a carrying capacity of 14,400. + +World geometry determines what shape your Avida grid will take. By default, the Avida universe is set to taking a toroidal (doughnut) shape. The creators of Avida chose this so that there are no edges in the universe and so that each organism has equal access to resources and neighbors. If, however, having boundaries and edges in your universe is important, you can change the shape of the Avida world to a bounded grid, hexagonal, random connected, and more. Details for what options exist for this setting and what they mean can be found in the avida.cfg file. + +_Where to do it_ + +Both world size and world geometry are set in the avida.cfg file. World size is controlled by the WORLD_X and WORLD_Y controls; world geometry is controlled by the WORLD_GEOMETRY control. Similar to most grid systems, the width is controlled by the WORLD_X control and the height is controlled by the WORLD_Y control. + +_How to do it_ + +To make changes to the default settings for world size and world geometry, 1) find the variables mentioned above in the avida.cfg file, 2) highlight and replace the current values with the ones you selected, and 3) save the file with your new changes. + +## 2. Stock the environment with organisms. + +_Why you need to do this_ + +An experiment can’t run without any organisms to evolve. If you don’t load an organism into the Avida config file, it would be like conducting a culture experimentβ€” without any organisms in the petri dish. + +_What you can do_ + +Avida comes with a number of different organisms you can use to populate your Avida world. Most experiments will use the basic Avida organism (defaultΒ­heads.org). This organism is haploid and asexual. For your first Avida experiments, it is highly recommended that you use the basic Avida organism. Only if your experiment explicitly calls for a different organism should you consider using a different Avida organism. + +_Where to do it_ + +Organisms are stocked (or β€œinjected”) into Avida in the events.cfg file. The command that controls what organisms are injected is the β€œInject” function located here. + +![Events File Screenshot](http://devosoft.org/wp-content/uploads/2015/08/EventsFile2.png) + +_How to Do it_ + +By default, Avida will inject the basic Avida organism (defaultΒ­heads.org). Unless you are changing this to a different organism, feel free to leave the file asΒ­is. + +## 3. Decide how organisms will be born and how organisms will die. + +_Why you need to do it_ + +The functions described in this setting give you control over how organisms enter and leave your Avida universe. Birth method determines where on the Avida grid new organisms are placed. Having control over this function allows you to mimic biological communities (if that’s important to your experiment) or to decide how organisms are dispersed across the Avida universe. + +Death method allows you to determine whether organisms in your world can die from old age or not. This distinction may be crucial for experiments that investigate longevity issues. Population cap controls determine how many organisms are allowed to exist in your Avida universe and, if the population cap is reached, the population cap eldest control will determine if a) the oldest organism in the universe dies or b) a random organism from the universe dies. + +_What you can do_ + +When it comes to placing new organisms in your Avida world, the birth method feature in Avida gives you a few options for where those organisms are placed. By default, new organisms are placed randomly onto the Avida grid. You can change this option, however, via the eleven birth method options found in the avida.cfg file next to the BIRTH_METHOD control. Some options include having new organisms facing the parent organism, replacing the oldest age in the neighborhood, or replacing the oldest within the entire population. + +The death method setting allows you to decide if an organism in your Avida world can die of old age or not. Avida has one setting for turning off this functionβ€” meaning that an organism will never die of old age. Avida has another setting for turning this function on, meaning that organisms who complete a certain number of instructions (i.e., AGE_LIMIT) will die. + +The population cap controls allow you to set a limit on how many organisms can exist in your Avida universe. While this is also partially controlled by the world size (see explanation in Step 1), the population cap can allow you to set an even smaller population maximum in your Avida world if having space and empty squares on the Avida grid is important to you. For example, let’s say I set my Avida world size to be 60 units high and 60 units wide. This would mean that I have set a de facto population cap of 3,600 (60 X 60) because Avida will only allow one organism to occupy a grid cell. + +But this also means that, unless other factors (such as competition or a population cap) come into play, the population will continue growing until it fills each of the 3,600 cells. IF, however, I wanted there to be some extra space protected in the Avida worldβ€” if my experiment called for there to be extra room between organisms β€” I could set a population cap of 3,000 organisms. This means that, no matter how large my world is, there will only ever be a maximum 3,000 organisms in the Avida universe. Setting a population cap allows you to protect empty space and/or to keep a more precise control over your maximum potential population size. + +Similarly, Avida allows you some flexibility over what happens to your Avida organisms when the population cap is reached. You can choose to a) kill off the oldest organism in the population or b) kill off a random member of the population. This choice is more or less critical depending on your research question(s), but should be thought over carefully when setting up your Avida experiment. + +_Where you do it_ + +The birth method and death method settings are found in the reproduction section of the avida.cfg file. Birth method is controlled by the BIRTH_METHOD variable and the death method is controlled by the DEATH_METHOD variable. Controls for the population cap settings, including POPULATION_CAP and POP_CAP_ELDEST, are located in the β€œgeneral group” section of the avida.cfg file. + +_How you do it_ + +To change Avida’s birth method (i.e., where new organisms are placed in the Avida grid), choose the option you would prefer from the avida.cfg documentation (located next to the BIRTH_METHOD control). Highlight and replace the preΒ­selected option (in this case, number 7) with the option you would prefer for your experiment. Be sure to save the file with your changes. + +To change the death method, locate the DEATH_METHOD variable in the avida.cfg file. By default, Avida is set to death method setting 2, which has a deathΒ­byΒ­oldΒ­age feature. If you wish to turn this off, highlight and replace the 2 with a 0 (0 is the setting for no death by old age). If you wish to have organisms die from old age, keep the file the same. + +To set a population cap, find the POPULATION_CAP control in the avida.cfg file, highlight the 0 (Avida defaults to 0/no population cap), and replace it with your population cap number (from our example above, this would be 3000). Do not use commas when writing in your population cap number in Avida. Once you’ve made your changes, save the avida.cfg file. + +The POP_CAP_ELDEST control works by entering in either a 0 (default) or 1 after the control name in the avida.cfg file. Select 0 for a random organism or 1 for the oldest organism to die if the population reaches the carrying capacity (i.e., population cap) you set for the population in the previous step. + +## 4. Stock the environment with resources. + +_Why you need to do this_ + +Just like in biological systems, Avida works by using competition for resources as a motivation for organisms to evolve characteristics that help them secure more resources and, thus, make them more likely to reproduce. In Avida, you have some control over how many resources are available to organisms in your experiment as well as how evenly (or not) those resources are distributed across the Avida grid. + +_What you can do_ + +By default, resources in Avida are infinite and undepletable. This means that there is never a shortage of a resource and that organisms are competing to acquire the most resources out of the infinite resource pool. They are not competing against each other for a limited number of resources. Furthermore, resources are, by default, dispersed evenly within the Avida environment. This means that there is no clustering of resources in a particular area. Organisms placed anywhere on the Avida grid will have equal access to resources. + +While most experiments work well with the default settings, you can change both the amount of resources available (i.e., create a depletable resource) or the dispersal pattern of the resources (i.e., create high and low resource concentration areas) to better answer your research questions. + +_Where you do this_ + +Any changes to the default settings of infinite and evenly dispersed resources are made in the environment.cfg file. +How you do this +Since most experiments don’t require changes to the default settings, changing the dispersal pattern and/or limiting the availability of resources requires more complex instructions. Those instructions, along with more description about what options are available to you, are located on the Avida documentation wiki [here](https://github.com/devosoft/avida/wiki/Environment-file). + +## 5. Decide what task(s) organisms will use to compete for resources and how they will/will not be rewarded for those tasks. + +_Why you need to do this_ + +In Avida, organisms complete logic functions to increase their merit. The more merit an organism in Avida has, the more CPU cycles it will receive. This means that the organism can reproduce faster and, eventually, become a more fit organism. As a researcher, you get to make choices about what logic tasks organisms in your Avida world will be asked to complete and how they will/will not be rewarded for completing these tasks. This will impact what types of behavior(s) you see evolving during your experiment. + +_What you can do_ + +It is important that you decide 1) what kinds of logic tasks organisms in your experiment(s) will be asked to complete, 2) how organisms in your experiment will be rewarded for completing those various tasks, and 3) how an organism’s merit gets added to its pre-Β­existing merit when it successfully completes a logic task. + +### Kinds of logic tasks + +By default, Avida will ask the organisms in your experiment to complete a series of nine logic tasks. This is often referred to in the Avida literature as the β€œdefault logicΒ­9 environment.” These nine logic tasks are listed in the environment.cfg file and move from relatively simple functions to more complex functions. For most experiments, the default logicΒ­9 environment provides a sufficiently complex environment. You can make the environment more complex, however, by adding additional logic tasks. There is a logicΒ­77 environment that adds such complexity but, again, most experiments work successfully with the default logicΒ­9 environment. + +Conversely, if you’re not really interested in looking at tasks or looking at evolved behavior, you can remove some logic tasks or remove the logic tasks all together. This can make your data easier to analyze and will prevent you from having to factor in evolvability later on in your experiment. + +### How organisms are rewarded +Avida allows you to control how organisms are rewarded for completing logic tasks. For every different logic task you ask your organisms to complete, you get to decide a point value reward for completing that task. By default, simple logic tasks receive less reward points than the more complex logic tasks. This is to ensure that organisms have sufficient motivation to attempt to complete the more complicated logic tasks. You can choose, however, to undo this default setting and reward all tasks the same. If you were interested in how a particular behavior evolves you could arbitrarily set the reward value for a certain function significantly higher and see how that impacts evolution. Because the options here are endless, it’s important to keep your research question(s) in mind when deciding how rewards are distributed in Avida. + +### How an organism’s merit is accumulated + +Every time an organism in Avida completes a logic task, it receives increased merit. You have to decide how that newly earned merit will be combined with the organism’s previously accumulated merit. By default, an organism’s merit increases exponentially. This encourages organisms to spend time solving more complicated logic tasks (even though they take more time) because the reward for completing those tasks is exponentially higher than the reward they would receive from completing simpler logic tasks. This also prevents an organism that completes many simple logic tasks from acquiring more merit than an organism who completes a few difficult logic tasks. + +While most experiments find the default settings to be a conducive way of encouraging the evolution of more complicated behavior, there are other settings that may be more appropriate for your particular research goals. More information about what other options are available and how they can be used in your experiment is located on the Avida documentation wiki [here](https://github.com/devosoft/avida/wiki/Environment-file). + +_Where you can do it_ + +All of the settings for logic tasks and task reward are located in the environment.cfg file. When you open the file, you will see the nine default logic tests laid out as in the following example: + +`REACTION NOT not process:value=1.0:type=pow requisite:max_count=1` + +Each line that starts with REACTION marks a different logic task. The variables listed after REACTION in each line determine the reward value, type, and restrictions for that logic task. Here’s an example of how to read these variables. + +In the examples above β€œNOT” would be the name of the logic task and β€œnot” would be the type of logic task (often, these are the same). So this tells you that this logic function is named β€œNOT” and will ask the organisms in your experiment to solve a logic problem that requires them to complete a β€œnot” logic task. (In Avida, this would be an organism correctly knowing to convert the sequence 001101 to 110010). + +The β€œprocess:value=1.0:type=pow” is the part of the REACTION line that determines how much merit an organism receives for completing that task and how that merit gets added to the organism’s preΒ­existing merit. The β€œvalue=1.0” part of the code assigns how much reward value (i.e., increased merit) an organism would receive from successfully completing that task. In this case, an organism gets 1.0 merit points for completing the task. The β€œtype=pow” part of the code determines how newly earned merit from completing this task will be combined with the organism’s preΒ­existing merit. In this example, an organisms merit is increased exponentially (the β€œpow” stands for power). This would mean that an organism would receive a 2^bonus or 2^1 for completing this task. + +The final part of this REACTION lineβ€” β€œrequisite:max_count=1” β€” sets a limit for how many times an organism can receive increased merit from completing this task. By default, this is set to 1, meaning that an organism would only receive increased merit the first time it completed that logic task. After that, the organism would not receive increased merit from repeating the same function. While this default setting encourages organisms to attempt increasingly complex behaviors, it may not work for all experiments and can be replaced with any value you choose. If your experiment requires that there is no merit cap on a particular logic function, you can delete the max_count=1 function completely so that the new code would read: + +`REACTION NOT not process:value=1.0:type=pow` + +_How you do it_ + +As we’ve seen in other portions of the Avida program, you make changes to these settings by highlighting the default value you wish to change and replacing it with your new value. For example, if I wanted to change how much merit an organism received from completing the NOT function in my experiment, I would highlight the source code where it says β€œ1.0” and replace it with a higher value, such as β€œ2.0” so that the final code would read like this (*'s to show changes): + +`REACTION NOT not process:value=**2.0**:type=pow requisite:max_count=1` + +If I also wanted to have the merit an organism receives from completing the NOT function to be +added to their previous merit (as opposed to being increased exponentially), I would highlight 7 +where it says β€œpow” in the documentation and replace it with β€œadd.” Again, the new REACTION line would read like this: + +`REACTION NOT not process:value=2.0:type=**add** requisite:max_count=1` + +If your experiment calls for less logic functions, you can delete a logic task by highlighting and +deleting the undesired logic task. Be sure to delete the _entire_ line, not just part of the command. + +It is also important that you not change either the task name (i.e., NOT) or task type (i.e., not) in the environment.cfg file. This will cause an error with your experiment. When you are done editing this file remember to save your changes. + +## 6. Decide how long your experiment will last. + +_Why you need to do this_ + +By default, Avida will run an experiment for 100,000 updates, where 10 updates are roughly equal to 1 generation. Depending on what type of experiment you’re doing, you may want to lengthen or shorten the default experiment runΒ­time. Setting the experiment update time is like deciding how long you want a certain bacteria to culture and/or how many generations of fruit flies you’re going to analyze. Shorter experiment times in Avida will take less time and will be much less data to analyze and store; however, longer experiments will allow you to see more longΒ­term +evolutionary patterns and population dynamics. + +_Where to do this_ + +The variable that controls the experiment length is located in the event.cfg file and is labeled β€œEXIT” (will be located near the bottom of the file). + +![Events File](http://devosoft.org/wp-content/uploads/2015/08/EventsFile2.png) + +_How to do this_ + +You can change the experiment update length by selecting the number 100000 and replacing it by typing in any positive whole number you select. Be sure to save the file before closing to update your changes. + +## 7. Decide what types of data you will collect from your experiment. + +_Why you need to do this_ + +Avida can collect and print a number of different types of data reports on any experiment. Depending on what your experiment is investigating, different types of data reports may or may not be as useful to you in answering your research question(s). Some of these data files are complex, take a long time to print, and use up a lot of computing/memory power on your device. Therefore, you can save yourself a lot of time and technological resources by intentionally selecting only the files you need Avida to print from your experiment. + +In addition to selecting what files to print, it is also important to select the frequency at which Avida prints your data files. By default, Avida prints a complete set of data files after every 100 updates for the entire duration of your experiment. Depending on how long your experiment lasts and/or if you’re looking at shortΒ­term or longΒ­term evolutionary patterns, this default print frequency might not make sense for your research. + +_What you can do_ + +The types of data files Avida can print are split into two groups: standard data files and nonΒ­standard data files. The standard data files are printed by default in Avida and will save basic data about what is happening in your experiment (more information about what is collected in each of the standard data files is located in the events.cfg file). + +The nonΒ­standard data files keep track of more nuanced and specific data. These files are not printed by default in Avida. Because these files often require that Avida make more calculations, these files take up more computational/memory space on your device. Therefore, it is recommended that you only print the nonΒ­standard data files that are essential to your experiment. Most experiments, especially at the beginner level, do not require any additional data files from the nonΒ­standard data files group. + +Avida also gives you a lot of control over when and how often the program prints data files. In particular, you can control three factors: 1) when Avida starts printing data files, 2) how many update cycles between data file printing, and 3) when Avida stops printing data files. + +You can choose any update cycle to begin and end data collection, and can print data files as frequently (i.e., every 10 updates) or infrequently (i.e., every 10,000 updates) as needed. + +_Where you can do this_ + +All settings to control data file printing are found in the events.cfg file. The standard data files are grouped together towards the beginning of the document and the nonΒ­standard data files are group together towards the end of the document. The print timing and frequency controls are located next to each data file in this document. + +_How you can do this_ + +Each data file is listed in the events.cfg file like this: + + `u 0:100:end PrintAverageData` + +To turn a data file on (i.e., print the file) remove the # from before the file name. Notice that the files in the standard file group don’t have a # at the beginning of the file name; that’s because they are printed (turned on) by default. If you choose to not print a certain data file, add a # to the beginning of the file name that you wish to turn off. For example, if you didn’t want to print the PrintAverageData file, you would insert an # before the u (i.e., `# u 0:100:end PrintAverageData`). The nonΒ­standard data files do have a # before their file name (i.e., `# u 100:100:end PrintTotalsData`). This means that, unless you remove the #, that file will not print. + +When Avida starts printing data, how often Avida prints a data file, and when Avida ends printing data are controlled by the three variables within colons. Taking our example from above, + +`u 0:100:end PrintAverageData` + +the β€œ0” would be when Avida starts printing this data file (i.e., at the 0th update), the β€œ100” would be the frequency at which Avida prints this data file (i.e., every 100 updates), and the β€œend” would be when Avida stops printing this data file (i.e., when the experiment ends). ReΒ­writing this example to the following, + +`u: 100:1000:10000 PrintAverageData` + +would tell Avida to a) start printing this file at the 100th update, b) print this data file every 1,000 updates, and c) stop printing this file at 10,000 updates (even if the experiment is still running). + +This documentation was produced by Rebecca Zantjer with consultation from members of the Devolab. \ No newline at end of file diff --git a/docs/documentation/Configuration-and-command-reference.md b/docs/documentation/Configuration-and-command-reference.md new file mode 100644 index 0000000..36c7a5a --- /dev/null +++ b/docs/documentation/Configuration-and-command-reference.md @@ -0,0 +1,25 @@ +## Main Configuration Files +* [[Avida.cfg|Avida.cfg]] +* [Events File](https://github.com/devosoft/avida/wiki/Events-file) +* [Environment File](https://github.com/devosoft/avida/wiki/Environment-file) +* [Instruction Set](https://github.com/devosoft/avida/wiki/Instruction-Set) +* [[instset-heads.cfg]] +* [[default-heads.org]] +* [Analyze File](https://github.com/devosoft/avida/wiki/Analyze-File) + +## Analyze Mode +* [[Analyze File]] +* [[Sample Analyze Programs]] + +## Subpopulations (Demes) +* [[Deme introduction]] +* [[Deme migration]] + +## Misc. Configuration +* [[Quirks]] +* [[Setting up Fixed-Length Organisms]] +* [[Introduction to Parasites]] +* [[Gradient Resources]] +* [[Internal resources]] +* [[Using mating types (separate sexes)]] +* [[Energy model configuration]] diff --git a/docs/documentation/Creating-a-flame-graph.mediawiki b/docs/documentation/Creating-a-flame-graph.mediawiki new file mode 100644 index 0000000..d2f03ed --- /dev/null +++ b/docs/documentation/Creating-a-flame-graph.mediawiki @@ -0,0 +1,59 @@ +A flame graph is a visual representation of genetic diversity and "speciation" through an Avida run, graphing genetic distance over time. It is related to a phylogeny, but it is not a phylogeny and should not be mistaken for (or used as!) one. + +1. Generating the Data + +First you must obtain the necessary data -- you need population detail files (historic files are not necessary) files. The default events.cfg generates these only every 50,000 updates, so you must change this to get finer timeslices. More timeslices yield a smoother graph, but also increase the storage space necessary for your run. I generally use time slices of 100 or 50 updates, because storage is cheap and I like smooth graphs. + +Once you have your population files, there are two ways to create a flamegraph. Choose according to your preferred tools: + +== Producing a Flame Graph with flamegraph.py == + +flamegraph.py is a Python script found in avida-core/source/utils/hist_map/ which uses matplotlib to produce the flamegraph. (It requires both Python and [http://matplotlib.sourceforge.net/ matplotlib] to work). It will handle both unzipped (.spop) and gzipped(.spop.gz) files. + +To run it: + +python flamegraph.py + +matplotlib can produce graphs in png, pdf, ps, eps, or svg format; choose the extension of your output file appropriately. + +In the current default Avida, the population detail files (.spop) use column 14 for phylogenetic depth and column 5 for number of organisms. (Older Avida population detail files with the .pop extension use columns 12 and 4, respectively.) Additionally, you will want to ensure that flamegraph.py reads the detail files the correct order, and that you include any files still gzipped. Altogether, your command should look something like this: + +python flamegraph.py flame.pdf 14 5 detail-?00.spop* detail-??00.spop* detail-???00.spop* detail-????00.spop* + + +When it has run, you may wish to check the reported number of rows -- it should be the number of detail files provided. + +(If you wish to immediately see the graph produced, you can add the -g flag. The -q flag will stop all those "Processing..." messages from appearing.) + +== Producing a Flame Graph with hist_map and Matlab == + +This is the "classic" method. + +1. hist_map + +If you have not already compiled hist_map, do so. It is located in source/utils/hist_map/, and you can simply use the Makefile. (Type "make" on the command line while in this directory.) + +Now run it: + +hist_map + +In the current default Avida, the population detail files (.spop) use column 14 for phylogenetic depth and column 5 for number of organisms. (Older Avida population detail files with the .pop extension use columns 12 and 4, respectively.) Additionally, you will want to ensure that hist_map reads the detail files the correct order. Altogether, your command should look something like this: + +hist_map 12 4 detail-?00.spop detail-??00.spop detail-???00.spop detail-????00.spop +When it has run, you may wish to check the reported number of rows -- it should be the number of detail files provided. + +2. Matlab + +Load the file created by hist_map into matlab, using zl or your favorite matrix-loading tool. E.g.: + +flame_matrix = zl(''); +What you will actually graph is the transpose of the log of this matrix + 1: + +flame_graphable = (log(flame_matrix + 1))'; +Finally, pcolor it -- for flame-colored flame graphs, use the hot colormap: + +colormap('hot') +flame_graph = pcolor(flame_graphable) +If at this point your flame graph is pure black, try the command + +shading flat diff --git a/docs/documentation/Default-Ancestor-Guided-Tour.md b/docs/documentation/Default-Ancestor-Guided-Tour.md new file mode 100644 index 0000000..55d2ac9 --- /dev/null +++ b/docs/documentation/Default-Ancestor-Guided-Tour.md @@ -0,0 +1,228 @@ +This document describes the structure of the classic virtual CPU and an example organism running on it. + +## The Virtual CPU Structure + +The virtual CPU, which is the default "body" or "hardware" of the organisms, contains the following set of components, (as further illustrated in the figure below). + +* A memory that consists of a sequence of instructions, each associated with a set of flags to denote if the instruction has been executed, copied, mutated, etc. Memory is treated as circular, such that execution will loop back to the first instruction after the last instruction has been executed +* An instruction pointer (IP) that indicates the next site in the memory to be executed. +* Three registers that can be used by the organism to hold data currently being manipulated. These are often operated upon by the various instructions, and can contain arbitrary 32-bit integers. +* Two stacks that are used for storage. The organism can theoretically store an arbitrary amount of data in the stacks, but for practical purposes we currently limit the maximum stack depth to ten. +* An input buffer and an output buffer that the organism uses to receive information, and return the processed results. +* A Read-Head, a Write-Head, and a Flow-Head which are used to specify positions in the CPU's memory. A copy command reads from the Read-Head and writes to the Write-Head. Jump-type statements move the IP to the Flow-Head. + + + + +## Instruction Set Configuration + +The instruction set in Avida is loaded on startup from a configuration file specified in the avida.cfg file. This allows selection of different instruction sets without recompiling the source code, as well as allowing different sized instruction sets to be specified. It is not possible to alter the behavior of individual instructions or add new instructions without recompiling Avida; such activities have to be done directly in the source code. + +The available instructions are listed in the inst_set.* files with a 1 or a 0 next to an instruction to indicate if it should or should not be included. Changing the instruction set to be used simply involves adjusting these flags. + +The instructions were created with three things in mind: + +* To be as complete as possible (both in a "Turing complete" sense -- that is, it can compute any computable function -- and, more practically, to ensure that simple operations only require a few instructions). +* For each instruction to be as robust and versatile as possible; all instructions should take an "appropriate" action in any situation where they can be executed. +* To have as little redundancy as possible between instructions. (Several instructions have been implemented that are redundant, but such combinations will typically not be turned on simultaneously for a run.) + +One major concept that differentiates this virtual assembly language from its real-world counterparts is in the additional uses of nop instructions (no-operation commands). These have no direct effect on the virtual CPU when executed, but often modify the effect of any instruction that precedes them. In a sense, you can think of them as purely regulatory genes. The default instruction set has three such nop instructions: nop-A, nop-B, and nop-C. + +The remaining instructions can be seperated into three classes. The first class is those few instructions that are unaffected by nops. Most of these are the "biological" instructions involved directly in the replication process. The second class of instructions is those for which a nop changes the head or register affected by the previous command. For example, an inc command followed by the instruction nop-A would cause the contents of the AX register to be incremented, while an inc command followed by a nop-B would increment BX. + +The notation we use in instruction definitions to describe that a default component (that is, a register or head) can be replaced due to a nop command is by surrounding the component name with ?'s. The component listed is the default one to be used, but if a nop follows the command, the component it represents in this context will replace this default. If the component between the question marks is a register than a subsequent nop-A represents the AX register, nop-B is BX, and nop-C is CX. If the component listed is a head (including the instruction pointer) then a +nop-A represents the Instruction Pointer, nop-B represents the Read-Head, and nop-C is the Write-Head. Currently the Flow-Head has no nop associated with it. + +The third class of instructions are those that use a series of nop instructions as a template (label) for a command that needs to reference another position in the code, such as h-search. If nop-A follows a search command, it scans for the first complementary template (nop-B) and moves the Flow-Head +there. Templates may be composed of more than a single nop instruction. A series of nops is typically abbreviated to the associated letter and separated by colons. This the sequence "nop-A nop-A nop-C" would be displayed as "A:A:C". + +The label system used in Avida allows for an arbitrary number of nops. By default, we have three: nop-A's complement is nop-B, nop-B's is nop-C, and nop-C's is nop-A. Likewise, some instructions talk about the complement of a register or head -- the same pattern is used in those cases. So if an instruction tests if ?BX? is equal to its complement, it will test if +BX == CX by default, but if it is followed by a nop-C it will test if CX == AX. + + +## Instruction Set Reference + +An abbreviated description of the 26 default instructions is below. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
(a-c) nop-A, nop-B, 
and nop-C + 		No-operation instructions; these modify other instructions.
(d) if-n-equ + Execute next instruction only-if ?BX? does not equal its complement
(e) if-less + Execute next instruction only if ?BX? is less than its complement
(f) if-label + Execute the next instruction only if the given template complement was just copied
(g) mov-head + Move the ?IP? to the same position as the Flow-Head
(h) jmp-head + Move the ?IP? by a fixed amount found in CX
(i) get-head + Write the position of the ?IP? into CX
(j) set-flow + Move the Flow-Head to the memory position specified by ?CX?
(k) shift-r + Shift all the bits in ?BX? one to the right
(l) shift-l + Shift all the bits in ?BX? one to the left
(m) inc + Increment ?BX?
(n) dec + Decrement ?BX?
(o) push + Copy the value of ?BX? onto the top of the current stack
(p) pop + Remove a number from the current stack and place it in ?BX?
(q) swap-stk + Toggle the active stack
(r) swap + Swap the contents of ?BX? with its complement.
(s) add + Calculate the sum of BX and CX; put the result in ?BX?
(t) sub + Calculate the BX minus CX; put the result in ?BX?
(u) nand + Perform a bitwise NAND on BX and CX; put the result in ?BX?
(v) h-copy + Copy an instruction from the Read-Head to the Write-Head and advance both.
(w) h-alloc + Allocate memory for an offspring
(x) h-divide + Divide off an offspring located between the Read-Head and Write-Head.
(y) IO + Output the value ?BX? and replace it with a new input
(z) h-search + Find a complement template and place the Flow-Head after it.
+ + +### An Example Ancestor + +The following organism is stored in the file organism.heads.15, which you should find in the support/config/misc/ directory. This is a simplified version of organism.default and +organism.heads.100, of lengths 50 and 100 respectively (each has additional instructions placed before the copy loop) + + +
# --- Setup ---
+
h-alloc # Allocate extra space at the end of the genome to copy the offspring into.
+
h-search  # Locate an + A:B template (at the end of the organism) and + place the Flow-Head after it
+
nop-C #
+
nop-A #
+
mov-head # Place the + Write-Head at the Flow-Head (which is at beginning of + offspring-to-be).
+
nop-C # [ Extra + nop-C commands can be placed here w/o harming the + organism! ]
+
  +
# --- Copy Loop ---
+
h-search # No template, + so place the Flow-Head on the next line code
+
h-copy # Copy a single + instruction from the read head to the write head (and advance both + heads!)
+
if-label # Execute the + line following this template only if we have just copied an + A:B template.
+
nop-C #
+
nop-A #
+
h-divide #     ...Divide off offspring! (note if-statement above!)
+
mov-head # Otherwise, + move the IP back to the Flow-Head at the beginning of the copy + loop.
+
nop-A # End label.
+
nop-B # End label.
+
+ +This program begins by allocating extra space for its offspring. The exact amount of space does not need to be specified -- it will allocate as much as it is allowed to. The organism will then do a search for the end +of its genome (where this new space was just placed) so that it will know where to start copying. First the Flow-Head is placed there, and then the Write-Head is moved to the same point. + +It is after this initial setup and before the actual copying process commences that extra nop instructions can be included. The only caveat is that you need to make sure that you don't duplicate any templates +that the program will be searching for, or else it will no longer function properly. The easiest thing to do is insert a long sequence of nop-C instructions. + +Next we have the beginning of the "copy loop". This segment of code starts off with an h-search command with no template following it. In such as case, the Flow-Head is placed on the line immediately following the search. This head will be used to designate the place that the IP keeps returning to with each cycle of the loop. + +The h-copy command will copy a single instruction from the Read-Head (still at the very start of the genome, where it begins) to the Write-Head (which we placed at the beginning of the offspring). With any copy command there is a user-specified chance of a copy mutation. If one occurs, the Write-Head will place a random instruction rather than the one that it gathered from the Read-Head. After the copy occurs (for better or worse), +both the Read-Head and the Write-Head are advanced to the next instruction in the genome. It is for this reason that a common mutation we see happening will place a long string of h-copy instruction one after another. + +The next command, if-label (followed by a nop-C and a nop-A) tests to see if the complement of C:A is the most thing copied. That is, if the two most recent instructions copied were a nop-A followed by a nop-B as is found at the end of the organism. If so, we are done! Execute the next instruction which is h-divide (when this occurs, the read and write heads will surround the portion of memory to be split off as the offspring's genome). If not, then we need to keep going. Skip the next instruction and move on to the mov-head which will move the head specified by the nop that follows (in this case nop-A which is the Instruction Pointer) to the Flow-Head at the beginning of the copy loop. + +This process will continue until all of the lines of code have been copied, and an offspring is born. + + +### An Example Logic Gene + +Here is a short example program to demonstrate one way for an organism to perform the "OR" logic operation. This time I'm only going to show the contents of the registers after each command because the functionality of the individual instructions should be clear, and the logic itself won't be helped much by a line-by-line explanation in English. + + +
Line # + Instruction + AX + BX + CX + Stack + Output +
1 IO + ? X ? + ? ? +
2 push + ? X ? + X, ?   +
3 pop + ? X X + ?   +
4nop-C   +
5 nand + ~X X X + ?   +
6nop-A   +
7 IO + ~X Y X + ? X +
8 push + ~X Y X + Y, ?   +
9 pop + ~X Y Y + ?   +
10nop-C   +
11 nand + ~X ~Y Y + ?   +
12 swap + Y ~Y ~X + ?   +
13nop-C   +
14 nand + Y X or Y ~X + ?   +
15 IO + Y Z ~X + ? X or Y +
diff --git a/docs/documentation/Default-heads.org.md b/docs/documentation/Default-heads.org.md new file mode 100644 index 0000000..7e6169b --- /dev/null +++ b/docs/documentation/Default-heads.org.md @@ -0,0 +1 @@ +The default ancestor organism when using the Heads virtual CPU. \ No newline at end of file diff --git a/docs/documentation/Deme-introduction.mediawiki b/docs/documentation/Deme-introduction.mediawiki new file mode 100644 index 0000000..ca10abc --- /dev/null +++ b/docs/documentation/Deme-introduction.mediawiki @@ -0,0 +1,15 @@ +
+

(Material adapted from Heather Goldsby's dissertation... so, it's a bit formal.)

+

To study group behavior with Avida, we divide the population of digital organisms into distinct subpopulations and link their long-term fates. Groups (also referred to as demes or colonies) can comprise a set of genetically-clonal or genetically-heterogeneous organisms. Β As with individual organisms, entire groups replicate and compete for space, but at a much greater time-scale.

+

Group Competition

+

There are two different forms of group competition. Both types of group competition result in group replication. First, for some experiments, we use tournament selection in which groups compete every 100 updates based on a fitness function, where a group's success is determined by the behavior of its constituent organisms. Each tournament contains a set of groups selected at random, and the group with greatest fitness is replicated (ties are broken randomly).Β Second, some of our experiments use task-based group competition (or deme replication event), where a group replication event is triggered by the collective behavior of individuals within a group. For example, a group could be set to replicate once its constituent organisms have consumed a certain amount of resources. (See create a deme replication event for a tutorial on how to make this work.)

+

 

+

FAQ:

+
+
    +
  • How do I set the size of a deme?Β Β The deme x-dimension is that of the world (WORLD_X) and the deme y-dimension is the y-dimension of the world divided by the number of demes (WORLD_Y/NUM_DEMES). So, for example, if you want 400, 5x5 demes, WORLD_X = 5, WORLD_Y=2000, NUM_DEMES=400. Demes are essentially placed in a long vertical line in the world.Β 
    • +
  • How many demes should I use?Β Ug. This part gets a little tricky. By default, most of us have used 400, 5x5 demes. This provides a reasonable runtime on the HPC and only hogs 2 gigs of memory per node. More demes or larger demes consume proportionally more resources.Β 
    • +
  • How do you populate demes at the start of a run?Β There are quite a few different inject options that work with demes. Two common ones are to use InjectAll, which injects the ancestor organism (controlled by theΒ START_ORGANISM configuration option)Β into all cells in all demes, and InjectDemes, which injects the ancestor organism into one cell per deme. Check out the complete list of actions for more options.Β 
    • +
+ +[[How to create a deme replication event]] diff --git a/docs/documentation/Deme-migration.mediawiki b/docs/documentation/Deme-migration.mediawiki new file mode 100644 index 0000000..632b386 --- /dev/null +++ b/docs/documentation/Deme-migration.mediawiki @@ -0,0 +1,25 @@ +

Subpopulation migration in Avida is supported by the assignment of "migration weights" for connections between subpopulations. The migration "topology" between subpopulations is defined through reading in a connection-weight matrix in the following format:Β 
Β 

+

# BEGIN
# All text beyond the '#' character in a file is a comment and will not be read in by Avida
# Subpop: Β  Β  Β  Β [0] Β  Β  Β  [1]Β Β  Β  Β [2] Β  Β  [3]
Β  Β  Β  Β  Β  Β  Β  Β  Β  Β  Β  Β 5.0, Β  0.10, Β  0.0, Β  4.0 Β  Β # [0] Β  Β  Β Row[0].Sum = 9.10
Β  Β  Β  Β  Β  Β  Β  Β  Β  Β  Β  Β 3.0, Β  0.20, Β  0.8, Β  2.0 Β  Β # [1] Β  Β  Β Row[1].Sum = 6.00
Β  Β  Β  Β  Β  Β  Β  Β  Β  Β  Β  Β 7.0, Β  0.30, Β  0.0, Β  1.0 Β  Β # [2] Β  Β  Β Row[2].Sum = 8.30
Β  Β  Β  Β  Β  Β  Β  Β  Β  Β  Β  Β 2.0, Β  1.30, Β  9.0, Β  0.0 Β  Β # [3]Β Β  Β  Β Rom[3].Sum = 12.30
# END

+


What this file means: The above un-commented text shows a simple 4-line file with each line containing 4 comma-separated values. Each row in the connection matrix contains all the connection weights *from* subpopulation[row] to other subpopulations that are indexed by column. For example, the connection weight between Subpopulation[1] and Subpopulation[2] is 0.8 where the from-subpopulation is row index 1 and to-subpopulation is column index 2. By setting each of these weights, you can specify what the appropriate migration probability will be from a given subpopulation to another subpopulation. Internally, when a migration event is going to occur from a given subpopulation (let's assume Subpopulation[1]), Avida will sum up the values in row 1 of the connectivity matrix (3.0 + 0.20 + 0.8 + 2.0 = 6.00) and generate a random number between: 0 and Row[1].Sum. This random number will be used to determine which subpopulation the organism will migrate into using a "roulette selection" protocol where each connection is represented by its weight's proportion of the sum. Β As you may have noticed, the sum of a row does not have to equal 1.0 as a typical probability matrix does. The probability matrix would be an exclusive subset of the type of connectivity matrices you can use under this setup.Β 
Restrictions for this file (and why):

+
    +
  1. The number of rows must equal the number of demes which must equal the number of columns in each row - This assumes that you will provide a connection weight value for every subpopulation pair possible. This is easier to read for both us as researchers and the computer/programmer :)
    2. +
  2. A row's sum cannot equal 0.0Β - Minimally, there must be a path for migration to occur and the control/null case is that the organism remains in its own subpopulation.Β Β Therefore, to use the migration matrix but turn migration among subpopulations OFF, one can simply supply the identity matrix where the diagonal is the only non-zero value (or just not use the migration matrix method ).Β 
    3. +
  3. A matrix entry cannot be negativeΒ - Intuitively, a negative migration value does not carry much meaning when trying to determine where an organism will migrate to and therefore, this will not be allowed.
    4. +
+

 

+

To turn on and use subpopulation migration, the following configuration parameters in *avida.cfg* will need to be set appropriately:Β 

+

(1)Β MIGRATION_FILE -- This config setting should be set to the migration file name that you want Avida to initialize with. Note: This file must be contained in the same working directory as your avida.cfg, events.cfg, and other Avida-related files. This setting is only used by Avida when the DEMES_MIGRATION_METHOD is set to use the migration matrix, otherwise a dummy value can be left here.Β 

+

(2)Β NUM_DEMES - This value specifies the total number of subpopulations in the run and it is *critical* that your MIGRATION_FILE's connectivity matrix have NUM_DEMES rows and that each row has NUM_DEMES columns.Β 

+

(3)Β DEMES_MIGRATION_RATEΒ - This value can be between 0.0 and 1.0 and essentially specifies the "success rate" that a triggered migration event will actually take place. When set to 0.0, migration will *never* occur and when set to 1.0, a triggered migration rate will *always* succeed and use the DEMES_MIGRATION_METHOD. If this value was set to 0.50, for example, it would mean that a migration event would trigger but that 50% of the time the actual migration action would not occur.Β 

+

(4)Β DEMES_MIGRATION_METHODΒ - This config setting should be set to 4Β to use the new connection matrix setup. Rather than the pre-built migration methods (Any other deme,Β Eight neighboring demes,Β Two adjacent demes in list, etc.), the "4" setting specifies to use the weights within the migration matrix to determine where an organism should migrate to.Β 

+

 

+

Deme Migration Events (can be added in your events.cfg)

+
    +
  • SetMigrationMatrix - The SetMigrationMatrix event takes one argument/parameter which is the filename of a *new* migration matrix to be used to replace the current one. For example, if a user wanted to "turn off migration at update 10,000", he/she could add a line into events.cfg that reads as follows: "u 10000 SetMigrationMatrix migration2.cfg". At update 10,000, this event would be triggered causing the migration2.cfg file (containing connection values only on the diagonal) to be used. Note: This migration file must adhere to the restrictions stated above, otherwise Avida will report an error and exit mid-run.
    • +
  • AlterMigrationConnectionΒ - To provide more fine-grained control over how connection weights change, theΒ AlterMigrationConnection event can be used in place of SetMigrationMatrix. This event takes *3* arguments: (1) from-index, (2) to-index, (3) alter_amount. When triggered, this event will go to the weight indexed by [from-index][to-index] and add the alter_amount value to the current weight. Naturally, if you wanted to decrease the current weight, you would simply make the alter_amount argument a negative value. By using the standard event protocol in Avida that has [start:interval:end], it is possible to cause a connection weight to change over a period of time by a certain amount. For example, if a user wanted to "decrease the connection between Subpopulation 0 and Subpopulation 1 by 3 units every 100 updates from update 10,000 to update 20,000" the corresponding event would be: "u [10000:100:20000] AlterMigrationConnection 0 Β 1 Β -3.0". Note: Every time this event is triggered it will alter the last updated amount for that connection, if the matrix entry value goes negative or if the row's sum becomes 0.0, an error will be flagged and the run will exit. (This will likely need fixing in the future .. but for now keep it in mind)
    • +
  • DumpOffspringMigrationCountsΒ - The DumpOffspringMigrationCounts action can be used to output how many organisms have migrated between the subpopulations (demes) in Avida. Each file that is outputted will appear in the data/ folder as follows: counts_offspring_migration.[update].dat.Β Β The [update] will contain the update # at which the file was dumped to the folder. The file is internally structured as a comma-separated (CSV) file containing a total of NUM_DEMES individual lines and each line containing NUM_DEMES comma-separated values (exactly like the MIGRATION_FILE). A 2D index into this CSV matrix (say the Yth CSV-value on line X) returns the number of offspring that migrated fromΒ subpopulation X toΒ subpopulation Y. *Note*: After each dump, all migration counts are reset to zero, therefore, if you want the total number of migrations that occurred in the entire run, you would need to sum up the respective values across all files dumped. An example of this command is: "u 100:200:end DumpOffspringMigrationCounts"Β where the user wanted to "dump the offspring migration counts starting at update 100 for every 200 updates until the end of the run."Β 
    • +
  • DumpParasiteMigrationCountsΒ - The DumpParasiteMigrationCounts action can be used to output how many parasites have migrated between the subpopulations (demes) in Avida. Each file that is outputted will appear in the data/ folder as follows:Β counts_parasite_migration.[update].dat.Β Β The [update] will contain the update # at which the file was dumped to the folder. The file is internally structured as a comma-separated (CSV) file containing a total of NUM_DEMES individual lines and each line containing NUM_DEMES comma-separated values (exactly like the MIGRATION_FILE). A 2D index into this CSV matrix (say the Yth CSV-value on line X) returns the number of parasites that migratedΒ fromΒ subpopulation XΒ toΒ subpopulation Y. *Note*: After each dump, all migration counts are reset to zero, therefore, if you want the total number of parasite migrations that occurred in the entire run, you would need to sum up the respective values across all files dumped. An example of this command is:Β "u 100:200:end DumpParasiteMigrationCounts"Β where the user wanted to "dump the parasite migration counts starting at updateΒ 100Β for everyΒ 200Β updates until theΒ endΒ of the run."
    • +
+
Hopefully this wiki article is of benefit for others who want to explore migration using Avida. If you have any questions/comments about the implementation, please feel free to contact me (Chad Byers) at byerscha@msu.eduΒ 
+
Β 
+
For Developers: To see where,Β in the source files, that updates/revisions have been made to support subpopulation migration, use the *Find All* feature in your IDE and search for "MIGRATION_MATRIX"
diff --git a/docs/documentation/Developers-Guide.md b/docs/documentation/Developers-Guide.md new file mode 100644 index 0000000..3fcfa93 --- /dev/null +++ b/docs/documentation/Developers-Guide.md @@ -0,0 +1,23 @@ +We welcome all those interested to contribute to the development and improvement of the Avida project. This developer’s guide will describe how to get started, the guidelines for contributions, and where to find ideas for what is needed. + +## Project Structure +Avida consists of several modules/sub-projects. + +* [Avida-Core Library](Development-|-avida-core) +* [Avida-Viewer Library](Development-|-avida-viewer) +* [Avida2 Frontend](Development-|-avida2) +* [The OS X/iOS Viewers](Development-|-viewer-macos) +* [The Windows Viewer](Development-|-viewer-windows) + +### [Getting Started](Development-|-Getting-Started) +### [Coding Style Guide](Development-|-Coding-Style-Guide) + + +## Mini Tutorials +* [A Conceptual Introduction to C++](Development-|-Tutorial-|-C-Plus-Plus-Intro) +* [Guide to the Death/Birth Cycle](Development-|-Tutorial-|-Birth-Death-Cycle) +* [Guide to an Avida Organism Life Cycle](Development-|-Tutorial-|-Life-Cycle) +* [The Building Blocks of the Virtual CPU](Development-|-Tutorial-|-Genome) +* [The Environment Source Code](Development-|-Tutorial-|-Environment) +* [Instruction Implemention Checklist](Development-|-Tutorial-|-Instruction-Checklist) +* [Environment Task Implementation Checklist](Development-|-Tutorial-|-Task-Checklist) diff --git a/docs/documentation/Development | Tutorial | Instruction Checklist.md b/docs/documentation/Development | Tutorial | Instruction Checklist.md new file mode 100644 index 0000000..bd76c48 --- /dev/null +++ b/docs/documentation/Development | Tutorial | Instruction Checklist.md @@ -0,0 +1,303 @@ +

+This document discusses how to implement your own instructions. +

+ + +

 

+

1. Build the method to be attached to the new instruction

+ +

+For this first step, you will be editing the virtual CPU definition in +cHardwareCPU.h and cHardwareCPU.cc, both of which are +found in the directory source/cpu/. Start by going to the +final section of the class definition in the header file and writing +the declaration for the new method that will be called whenever the +instruction is executed. For example, if you were going to add the +instruction minus-17 (which performs the oh-so-useful behavior +of subtracting 17 from the ?BX? register), you would add the line: +

+
+bool Inst_Minus17(cAvidaContext& ctx);
+
+ +

+If possible, place it near other instructions of the same type. There are +about a hundred methods cHardwareCPU. This instruction would likely fit best +with the group of instruction described as "Single-Argument Math". +That is, all those instructions that perform mathematical operation that only +affect a single register. +

+

+All methods associated with instructions return a +bool value that determines if it was +successfully executed. Most instructions will always return true since they +have no way to fail. The convention that we use to designate a method +explicitly associated with an instruction is placing a prefix of +Inst_ in front of it. +

+

+Next, you have to write the function body in the code file +(cHardwareCPU.cc). The method bodies will be listed at the end of +this file in the same order that they were declared in the header. You would +find the proper position, and write something to the effect of: +

+ +
+bool cHardwareCPU::Inst_Minus17(cAvidaContext& ctx)
+{
+  const int reg_used = FindModifiedRegister(REG_BX);
+  GetRegister(reg_used) -= 17;
+  return true;
+}
+
+ +

+The first line of this method uses a helper function called +FindModifiedRegister() to identify the register +that should be affected (it scans the next instruction to test if it is a +nop), with a default value of REG_BX passed in. +The second line then subtracts 17 from the value in that register. The +constant values and available helper functions will be described in more +detail below, as will a guide to accessing the components in the virtual +CPU. For the moment, you have finished implementing the method! +

+

+Note that this would be a good time to recompile if you want to test how +well your implementation is going so far. +

+ + +

 

+

2. Link the instruction name to its method

+ +For this step, you will need to edit the code file. You would go into the method +cHardwareCPU::initInstLib(void) +and add in the line + +
+cInstEntryCPU("minus-17", &cHardwareCPU::Inst_Minus17);
+
+ +

+in the same order that it was defined in the class definition. +

+

+Since we want to use a pointer to the appropriate method, that is what we +must pass into the dictionary. To obtain said pointer, we must list the class +the function is part of (cHardwareCPU) follow it +by a double colon (::) and then give the method name +(Inst_Minus17) without the normal +parentheses following it. The parentheses indicate that we should execute +the method. Without them, it is just the data that represents the method, +and by preceding this whole mess with an ampersand ('&') we get the pointer +to the location in memory that the method resides. +

+

+IMPORTANT: If your instruction interacts with the population, resources, +or IO, make sure to flag the instruction for speculative stall by adding a third + argument, nInstFlags::STALL. For an example, look at the 'h-divide' + instruction. +

+

+Compile again, and you should have your instruction ready for use. +

+ + +

 

+

3. Add the entry to your instruction set and test it!

+ +

+This last part should be the easiest. If you want the new instruction you +just created to be loaded on startup, you must add a line in the instruction +set you are using (specified in the configuration file) to indicate its +inclusion: +

+
+minus-17 1
+
+ +

+And there you have it! Now the real trick is to test if its working +properly. I'd recommend using as a framework the creature +default-classic.org and modifying some of the long series of +nop-C instructions inside of it to perform some math using the +new instruction (only the very first nop-C cannot be changed). You +can then either go into zoom mode in the viewer and step through the creature, +or else use analyze mode trace its execution. If you are going to use zoom +mode, setup your modified creature as the START_CREATURE in configuration file. +If you want to use analyze mode, put the following lines into the +analyze.cfg file in your work/ directory: + +

+  LOAD_ORGANISM inst_test.org
+  TRACE
+
+ +

+Where you have to replace inst_test.org with the name of the +organism you want to trace. The new file will appear in the +data/archive/ directory, with the same name as the one you loaded +in, but a .trace appended to the end. +

+ + +

 

+

CPU Components

+ +

+Various CPU components are often manipulated by instructions, and we +need a standard way of doing this. We have settled on each component being +associated with a method to access it, to provide a single location that can +control that access. This has already been useful -- in a multi-threaded +CPU (i.e., a CPU that has multiple positions in its genome being executed at +the same time) each thread has its own registers and heads, so we need to +always be sure we are manipulating the component of the active thread. If +you simply use the following methods, they will always find the correct +component for you. +

+ +
+
+
+void StackPush(int value);
+int StackPop();
+void SwitchStack();
+
+
+
+There are two stacks in a normal CPU, and more in a multi-threaded version +(one global stack, and one local to each thread). The first stack method will +place a new value on the top of the currently active stack, the second will +remove the top value, and the last will toggle the currently active stack. +
+
+
+cCPUHead& GetHead(int head_id);
+cCPUHead& IP();
+
+
+Each thread in a CPU has four heads associated with it, designated by the +constants HEAD_IP, HEAD_READ, +HEAD_WRITE, and HEAD_FLOW. These heads each point +to a position in memory, and all have their own purpose. A head can be +accessed by passing the appropriate constant into the GetHead() method. The +extra method IP() was added to more easily obtain just the instruction pointer. +The IP is a very special head since it designates what instruction is going to +be executed next, and often it will make code clearer if you obtain it by +calling IP(). (It will show that you need to make sure of the special +qualities of the instruction pointer.) +
+
+
+int& Register(int reg_id);
+
+
+
+There are three registers available, associated with the constants +REG_AX, REG_BX, and REG_CX. If the +Register() method is called, an integer reference will be returned associated +with that register. Any change to this integer will make a corresponding +change to the register in question. +
+
+
+cCPUMemory& GetMemory();
+
+
+
+This method allows the programmer to access the full memory of the CPU. As +you know, the class cCPUMemory is built on top of Genome, so you can +manipulate it in all of the same ways. +
+
+ +

+These are only a sampling of the available methods of interacting with the +components of the CPU, but they give you a good cross-section without +overwhelming you with all of the possibilities. You should look through the +source files if you want to see the other options that are available to you. +

+ + +

 

+

Helper Methods

+ +

+There are several very common tasks that are performed during the execution +of many of the instructions. For each of these tasks we have created a +helper function to ease the creation of new instructions. +

+ +
+
+
+void ReadLabel();
+cCodeLabel& GetLabel();
+cCPUHead FindLabel(int direction);
+
+
+
+ReadLabel() will read in the label (series of nop instructions) that +immediately follows the instruction being executed. The label that was read +can then be accessed (and even modified) using GetLabel(). Finally, the +Findlabel() method takes single int argument that determines the direction +(from the instruction pointer) in which the label should be search for. If +this argument is a 1 it will search forward, and if its a -1, it will search +backwards. A zero indicates that the search should start from the beginning +of the genome, and proceed to the end. Once it finds the matching label, it +will return a head at the position in which the label was found. These +helper methods are particularly useful in any instruction that has to affect +other portions of the source code. See the method Inst_HeadSearch for an +example of how these are used. +
+
+
+int FindModifiedRegister(int default_register);
+int FindModifiedHead(int default_head);
+
+
+
+These two methods will look ahead and determine if a nop instruction is +immediately following the instruction being executed. If so, it will return +the register or head ID associated with that nop (for use in the rest of the +method), and if no nop is found, it will automatically return the +default value passed in. We used FindModifiedRegister in the example new +instruction above. +
+
+
+int FindComplementRegister(int base_reg);
+
+
+
+Several instructions are defined as affecting a certain, modifiable register +and its complement. In order to have a standard way of determining the +complement of a register (which, by default, cycle in the same order as +complement labels), we use this function whenever we need to determine one. +See, for example, see the definition of Inst_IfNEqu(). +
+
+ + +

 

+

Problem

+ +

+To test your understanding of adding instruction into Avida, try writing two +new instructions. The first one is the mathematical instruction +cube that will take the ?BX? register, and put +its value to the third power. If you look in the actual source files, you +will see that there is already a square instruction that you can +model this on. +

+

+Next, you will implement the instruction if-twice +that will execute the next instruction if-and-only-if the value in the ?BX? +register is twice that of the value in its complement. In other words by +default, if would test of BX was twice CX, but if it is followed by a +nop-C it will test if CX is twice AX. +

+

+For both of these instruction make sure to craft an organism to test that +they are working properly! +

diff --git a/docs/documentation/Development-|-Coding-Style-Guide.md b/docs/documentation/Development-|-Coding-Style-Guide.md new file mode 100644 index 0000000..574924b --- /dev/null +++ b/docs/documentation/Development-|-Coding-Style-Guide.md @@ -0,0 +1,298 @@ +

+This document describes the coding standards that should be followed +when developing within Avida. +

+ + +## C/C++ Dialect +
    +
  • ISO Standard C++ (1998/2003)
    • +
  • Do not use GCC extensions (such as multi-line strings and comments).
    • +
  • No compiler warnings with explicitly supported compilers, including GCC and Clang-LLVM.
    • +
+ + +## Code Formatting + +

Indentation

+
    +
  • + All source code indentation should be spaces. This includes C++, Python, + and HTML. +
    • +
  • + The size of a single indentation is 2 spaces. +
    • +
+ + + +

 

+

Braces

+ +
+

Function Definitions

+
+

+ Open and close braces should each be on their own line. Do not + place the open brace on the same line as the function signature. The only + exception to this rule is single line class methods, in which both braces + are allowed to be on the same line as the code (but only in pairs). Examples: +

+
Right:
+
+void cFoo::Method()
+{
+  // code goes here
+}
+
+// ... in a class
+inline void Method() { ; }
+
+inline void Method()
+{ // longer code in here }
+
+
Wrong:
+
+void cFoo::Method() {
+  // code goes here
+}
+
+// ... in a class
+inline void Method() { 
+  ; }
+
+ +
+ +

For, While, Do Loops and Switch Statements

+
+

+ The open brace should go on the same line as the control structure, + the close brace on its own line. Examples: +

+
Right:
+
+while (foo) {
+  // code goes here
+}
+
+
Wrong:
+
+while (foo)
+{
+}
+
+ +
+ +

If/Else Statements

+
+

+ The same formatting rules as for/while/etc., but if there is an else clause + the close brace should go on the same line as the else statement. Single + line if else statements should not get braces, unless they accompany a + multi-line statement. Examples: +

+
Right:
+
+if (foo) {
+  DoSomething();
+  DoAnotherSomething();
+} else {
+  DoADifferentSomthing();
+}
+
+if (!foo) CallAFunction();
+else CallBFunction();
+
+
Wrong:
+
+if (foo)
+{
+  DoSomething();
+  DoAnotherSomething();
+} else 
+  DoADifferentSomthing();
+
+if (!foo) {
+  CallAFunction();
+}
+else CallBFunction();
+
+
+
+ + +

 

+

Parentheses

+
+

Function Declarations and Calls

+
+

+ Do not use any space between the name and the open parenthesis, inside the + parentheses, or before commas that separate arguments. A single space + should follow commas that separate arguments. Examples: +

+
Right:
+
+void cFoo::Method(int arg1, double arg2);
+int aFunction();
+
+
Wrong:
+
+void cFoo::Method( int arg1 , double arg2 );
+void cFoo::Method (int arg1, double arg2);
+int Function ( );
+
+ +
+ +

Control Structures

+
+

+ Control structures such as if, for, while, do, and switch statements use a + single space before the open parenthesis, but spaces inside them. +

+
+
+ + +

 

+

Other Punctation

+
    +
  • + Pointer and reference types should be written with NO space + between the type name and the * or &. +
    • +
+ + +

 

+

Include Guards and Statements

+
    +
  • + All header files must use include guards, where the name of the guard is + exactly the filename with the period replaced with an underscore. For + example, cPopulation.h is guarded by: +
    +#ifndef cPopulation_h
+#define cPopulation_h
+
+// Code goes here
+
+#endif
+
    +
    • +
  • + Include statements in header (.h) and implementation (.cc) files must + not check include guards (no #ifndef blocks). This compile time + optimization is to be left for the compiler to perform. +
    • +
+ + +## Naming Conventions + +
    +
  • + Variable names should be all lowercase. Multi-word variables should have the + words separated by underscores ('_'). Examples: +
    +i
+position
+this_is_my_var
+
    +
    • +
  • + Class instance member variables should have the same format as regular + variables, but must be prefixed with 'm_'. Examples: +
    +m_type
+m_lexeme
+m_my_component
+
    +
    • +
  • + All functions and public struct/class methods should begin with a capital + letter followed by lowercase. Additional words should be signified by + capital letters. Underscores should only be used to indicate a category + of functions. Examples: +
    +Sort() 
+ThisIsMyFunction() 
+cHardwareCPU::SingleProcess()
+
    +
    • +
  • + Private and protected struct/class support methods should begin with a + lowercase letter. Additional words should be signified by capital letters. + Underscores should only be used to indicate a category of functions. Examples: +
    +cHardwareBase::doSlipMutation()
+cParser::parseCodeBlock()
+
    +
    • +
  • + All class names should begin capital letters leading each word (similar to functions). Examples: +
    +Genome
+Array
+HeadTypes
+SomeData
+
    +
    • +
  • + All constant values (even as listed in enumerations) should be in all + capital letters, with words separated by underscores. Examples: +
    +NUM_REGISTERS
+MAX_STRING_LENGTH
+
    +
    • +
  • + All filenames should be the same as the class defined within that file. + Header files should use .h; implementation files should use + .cc. + Examples: +
    +Genome.h
+Array.h
+Population.cc
+
    +
    • +
  • + Generally, there should only be one class defined in each header/source + file pair. Implementation helper classes should be defined as internal + class members. +
    • +
+ + +

 

+

Class Dependency Guidelines

+
+

+ Some groupings of classes should maintain important limitations with respect + to class dependency. +

+ +

Tools Classes

+
+

+ All classes developed as general utility classes should be placed within the + source/tools directory. These classes + should have no dependencies that extend outside of this directory. +

+
+ +

STL Usage

+
+

+ Usage of the Standard Template Library should be very limited. A number of + these templates have unspecified orderings that can vary across platforms, + affecting consistency. Where possible, it is greatly preferred to use the + local tools classes. +

+
+
diff --git a/docs/documentation/Development-|-Getting-Started.md b/docs/documentation/Development-|-Getting-Started.md new file mode 100644 index 0000000..ca41fe6 --- /dev/null +++ b/docs/documentation/Development-|-Getting-Started.md @@ -0,0 +1,59 @@ +These instructions will guide you through the process of setting up tools, obtaining the source code, building the suite, and provide an overview of the source code structure. + +## Development Tools +Avida is a cross platform project designed to work on most POSIX-compliant systems, such as Linux, Mac OS X, Unix-variants, and Windows. You will need a development environment for your platform, such as GCC on Linux, Microsoft Visual Studio on Windows, and Apple Xcode on Mac OS X. The cross platform build system uses CMake, version 2.6 or greater, to generate platform specific build files. In order to obtain the source code, you will need a recent copy of Git. + +## Getting the Source Code +The Avida project uses multiple Git repositories to manage the source code. If you are new to Git, see Using Git for an overview of basic usage. When developing in Avida, you should always work from a working copy of the Git repository to ensure that you may stay up to date with recent changes. To clone the master Avida repository, move to the directory where you want to store the clone and run the following: +
$ git clone https://github.com/devosoft/avida.git
+Note, however, that the Avida project uses the Apto library linked as a submodule. You must initialize the submodule following the clone command above before you will be able to build the project: +
$ cd avida
+$ git submodule init
+$ git submodule update
+At this point you should be able to proceed to compiling. + +## Compiling +### Unix Command Line - CMake +You will need a copy of CMake. +
    +
  1. At the top level of the source code run the ./build_avida script.
    2. +
    • To compile the avida-viewer, use the flag -DAVD_GUI_NCURSES with ./build_avida
    +
  2. Change into the directory cbuild/work
    3. +
  3. The compiled executables (avida, avida-viewer), as well as the sample configuration files will be present in the work directory.
    4. +
+### Mac OS X - Xcode +
    +
  1. Open the Avida.xcodeworkspace file in the top level of the source code.
    2. +
  2. Select the avida build scheme in the top left of the workspace window.
    3. +
  3. Select menu option Product > Archive
    4. +
  4. "Distribute..." the archive, "Save Built Products"
    5. +
  5. The archive contents will contain the executable in /usr/local/bin/avida and the example configuration files in /usr/local/share/avida
    6. +
+ +### Windows - Visual Studio +
    +
  1. Open the CMake GUI
    2. +
  2. Select the top level avida source code directory for the "Where is the source code" option.
    3. +
  3. Specify a director to build the project files and binaries. It is recommended that you create a new empty directory for this path.
    4. +
  4. Select your desired development system (Visual Studio version), if prompted or necessary.
    5. +
  5. Click Configure twice, then click Generate to generate the project files.
    6. +
  6. Open the generated Visual Studio solution file that should now be in your build folder.
    7. +
  7. Build the solution (build the install target, don't use build all).
    8. +
  8. You should find a work directory in your build folder containing the avida.exe and default configuration files.
    9. +
+Some other notes: +
    +
  1. In the options panel only APTO_LIB_SHARED, APTO_LIB_STATIC and AVD_CMDLINE should be 'On'. The viewer does not appear to build on Windows at the moment.
    2. +
  2. Can't find the executable? Check the bin/DEBUG or bin/RELEASE directories.
    3. +
+ +## Project Structure +The Avida project master repository has been organized in the structure described below. This overview should help locate where the sub-projects you are interested in may be found. See specific sub-project pages for further information. + +
Applications - /apps
Mac OS Viewer - /apps/viewer-macos
Cocoa-based GUI application supporting Avida and Avida-ED
Avida Core - /avida-core
The avida-core and avida-viewer libraries. The heart of Avida.
Libraries - /libs
Apto - /libs/apto submodule
Apto C++ tools library. Data structures and cross-platform support layer.
+ +## Contributing to the Repositories +There are two main ways to contribute code changes to the repositories of the Avida project. The community at large is encouraged to fork the repositories on GitHub and to submit pull requests as appropriate. More details about using GitHub is available on their site. + +Core developers who have been granted direct push access will need to utilize the authenticated remote repository path. The authenticated repository is git@github.com:devosoft/avida.git. If you are working from a standard clone of the source code, you may update your push URLs with the following commands: +
$ git remote set-url --push origin git@github.com:devosoft/avida.git
diff --git a/docs/documentation/Development-|-Tutorial-|-Birth-Death-Cycle.md b/docs/documentation/Development-|-Tutorial-|-Birth-Death-Cycle.md new file mode 100644 index 0000000..7b39679 --- /dev/null +++ b/docs/documentation/Development-|-Tutorial-|-Birth-Death-Cycle.md @@ -0,0 +1,228 @@ +

+This document describes the interaction between organisms and the population. +

+ + +

 

+

The Death of an Organism

+ +

+When an organism is killed off, its location in the population (that is, its +population cell) needs to be emptied, the scheduler needs to be notified, and +various statistics need to be updated to reflect the recently deceased. All of +this is handled with the method below. In a default Avida setup, this method +will only be called when a cell needs to be cleared out for a new occupant, +but you've already seen this method used when you implemented the kill-related +events in a previous homework. We'll see it also called from code displayed in +the next section of this document. +

+ +
+void cPopulation::KillOrganism(cPopulationCell& in_cell)
+{
+  // do we actually have something to kill?
+  if (in_cell.IsOccupied() == false) return;
+
+  // Statistics...
+  cOrganism* organism = in_cell.GetOrganism();
+  cGenotype* genotype = organism->GetGenotype();
+  m_world->GetStats().RecordDeath();
+
+  num_organisms--;
+  genotype->RemoveOrganism();
+
+  // And clear it!
+  in_cell.RemoveOrganism();
+  if (!organism->GetIsRunning()) delete organism;
+  else organism->GetPhenotype().SetToDelete();
+
+  // Alert the scheduler that this cell has a 0 merit.
+  schedule->Adjust(in_cell.GetID(), cMerit(0));
+
+  // Update the archive (note: genotype adjustment may be deferred)
+  m_world->GetClassificationManager().AdjustGenotype(*genotype);
+}
+
+ +

+This method takes as an argument the cell that needs to be emptied. It starts +off by making sure that the cell in question actually has an organism in it to +be killed. If not, it stops right there. If so, it records some statistics +about that organism's life, and updates its counter of living organisms to +reflect that there is one fewer. +

+

+Once the statistics are finished, the cell itself is cleared with the +cPopulationCell::RemoveOrganism() +method (in which the pointer to the organism it once contained is set to NULL). +At this point if the organism is not the currently running CPU it will be +deleted. Otherwise, a flag is set that marks the organism for deletion after +the current instruction has finished executing. Finally, the scheduler (which +is the object that doles out CPU cycles to the individual organisms) is updated +to reflect that this cell is now empty. +

+ + +

 

+

Activating an Organism in a Specific Cell

+ +

+If an organism is going to be placed into a specific cell of the population, +the method ActivateOrganism can be called on the population, telling it the +location in memory of the organism to be placed and the cell to place it in. +This method will call the KillOrganism() method +to make sure the cell is unoccupied. This method is called from the +Inject() method as well as +ActivateOffspring(), described below. +Here is the ActivateOrganism method: + +

+void cPopulation::ActivateOrganism(cAvidaContext& ctx, cOrganism* in_organism, cPopulationCell& target_cell)
+{
+  in_organism->SetOrgInterface(new cPopulationInterface(m_world));
+
+  // If the organism does not have a genotype, give it one!  No parent
+  // information is provided so we must set parents to NULL.
+  if (in_organism->GetGenotype() == NULL) {
+    cGenotype* new_genotype = m_world->GetClassificationManager().GetGenotype(in_organism->GetGenome(), NULL, NULL);
+    in_organism->SetGenotype(new_genotype);
+  }
+  cGenotype* in_genotype = in_organism->GetGenotype();
+
+  // Save the old genotype from this cell...
+  cGenotype* old_genotype = NULL;
+  if (target_cell.IsOccupied()) {
+    old_genotype = target_cell.GetOrganism()->GetGenotype();
+    
+    // Sometimes a new organism will kill off the last member of its genotype
+    // in the population.  Normally this would remove the genotype, so we
+    // want to defer adjusting that genotype until the new one is placed.
+    old_genotype->IncDeferAdjust();
+  }
+
+  // Update the contents of the target cell.
+  KillOrganism(target_cell);
+  target_cell.InsertOrganism(*in_organism);
+
+  // Update the archive...
+  in_genotype->AddOrganism();
+
+  if (old_genotype != NULL) {
+    old_genotype->DecDeferAdjust();
+    m_world->GetClassificationManager().AdjustGenotype(*old_genotype);
+  }
+  m_world->GetClassificationManager().AdjustGenotype(*in_genotype);
+
+  // Initialize the time-slice for this new organism.
+  schedule->Adjust(target_cell.GetID(), in_organism->GetPhenotype().GetMerit());
+
+  // Special handling for certain birth methods.
+  if (m_world->GetConfig().BIRTH_METHOD.Get() == POSITION_CHILD_FULL_SOUP_ELDEST) {
+    reaper_queue.Push(&target_cell);
+  }
+
+  num_organisms++;
+
+  // Statistics...
+  m_world->GetStats().RecordBirth(target_cell.GetID(), in_genotype->GetID(),
+                                  in_organism->GetPhenotype().ParentTrue());
+}
+
+ +

+The first thing we do build a new interface object and attach it to the +organism object. Next we check to see if the organism has already been +assigned its genotype. If an organism was born from a parent in the population, +it will have been assigned a genotype by the time this method is called. If it +does not have a genotype, however, the classification manager object will be +called to look up any genotypes that match this genome. The classification +manager will either return an exact match, or else create a new genotype, add it +to the archive, and return its pointer. In either case, we now have a genotype +for this organism. +

+

+Before we erase the organism currently in this cell, we want to keep track of +what genotype it was part of for use in updating the archive later. We then +kill the organism in the cell (as described above) and insert the new one. +The cPopulationCell::InsertOrganism() +method will setup the organism based on the environmental conditions of this +cell (mutation rate, tasks rewarded, etc), and store the organism for future +use. +

+

+We then adjust the genotype to let it know a new organism of its type has +been created, and tell the classification manager that it should also adjust +the genotypes to reflect their new abundances (one genotype has grown by one, +the other has shrunk, so the genotype ordering may change). Other maintenance +we need to do at this point includes adjusting the scheduler to let it know the +merit of this new organism, and the reaper_queue if we keep track +of the birth order of organisms so that we can always kill off the oldest in +the population. +

+

+Finally, we adjust some more statistics by incrementing the number of +organisms in the population and let the statistics object know that a new +organism was born, with all of its information. Remember, if this cell was +already occupied, KillOrganism() would have decremented it, so this will +properly reflect the number of organisms alive in the population at any moment. +

+ + +

 

+

Placing an Offspring in the Population

+ +

+When an organism gives birth, we must collect some relevant statistics, +which can best be accomplished in the population object. Then we must +place the offspring into its own cell in the population. This is all done +with the cPopulation::ActivateOffspring +method. This method takes as arguments the parent organism and child genome +that we're working with. It is called by the divide command via the +population interface. As this method is quite long, refer to it in the source +code in cPopulation.cc while reading the remainder of this section. +

+

+The first step in activating an offspring involves performing some book keeping +on the parent's phenotype via the DivideReset() +method. After this, the child genome is submitted to the birth chamber. The +birth chamber is responsible for handling the details of reproduction, such as +genome recombination in sexual populations. The +SubmitOffspring() method will add organism objects +to the child_array for each offspring produced. +

+

+The next section of code is in charge of finding where in the population each +child organism should be placed. The cell of the parent is looked up, and then +the PositionChild() method is called to determine +the child's cell. +

+

+If the parent is not about to be killed off (due to being replaced by one of +the children), we actually want to do a bit more work -- we need to adjust +it in the schedule in case its merit has changed over this gestation cycle, +and (if we are on a grid) we want to turn the child so that it is facing +its parent. +

+

+Finally, we collect a bunch of statistics for the parent's genotype object, +and we run ActivateOffspring for each offspring produced using the cell we have +chosen in order to place the child into the population. +

+ + +

 

+

Injecting an Organism into the Population

+ +

+Injecting a genome into the population that does not have a parent (such as +with the Inject action) is somewhat easier to deal with. +Basically, all that this method needs to do is build the organism with the +proper genome, determine its genotype, setup its phenotype, put it into a +test CPU to get its initial merit, and activate it! You should be able to +go line-by-line through the code to see how exactly this happens for +yourself. See +cPopulation::InjectGenome, +and more importantly +cPopulation::InjectGenotype +in cPopulation.cc. +

diff --git a/docs/documentation/Development-|-Tutorial-|-C-Plus-Plus-Intro.md b/docs/documentation/Development-|-Tutorial-|-C-Plus-Plus-Intro.md new file mode 100644 index 0000000..c06fc26 --- /dev/null +++ b/docs/documentation/Development-|-Tutorial-|-C-Plus-Plus-Intro.md @@ -0,0 +1,395 @@ +

+This file will cover in more detail some of the concepts needed to understand +C++. The goal here is not to make you be able to sit down and write +your own program from scratch. +

+ + +

 

+

Objects and Classes

+

+An object in C++ is a single, conceptual unit that contains +data (information about the state of that object) and +methods (functions associated with that class of objects) by +which the object is modified or can interact with other objects. The data in +an object can be either normal variables (e.g. characters, floating +point numbers, or integers) or previously-defined objects. A category of +objects is a class; an object is a single instance of a class. +

+

+For example, in Avida one of the most important classes is called cOrganism +-- it is the class that all organism objects belong to. Here is an abbreviated +version of the cOrganism class declaration (explained further below). + +

+class cOrganism
+{
+private:                     // Data in this class cannot be directly accessed from outside.
+  const Genome m_genome;    // The initial genome that this organism was born with.
+  cPhenotype m_phenotype;    // Maintains the status of this organism's phenotypic traits.
+
+  cOrgInterface* m_interface;  // Interface back to the population.
+
+  cGenotype* m_genotype;     // A pointer to the genotype that this organism belongs to.
+  cHardwareBase* m_hardware; // The virtual machinery that this organism's genome is run on.
+
+public:                     // The methods are accessible to other classes.
+  cOrganism(cWorld* world, cAvidaContext& ctx, const Genome& in_genome);
+  ~cOrganism();
+
+  // This batch of methods involve interaction with the population to resolve.
+  cOrganism* GetNeighbor() { return m_interface->GetNeighbor(); }
+  int GetNeighborhoodSize() { return m_interface->GetNumNeighbors(); }
+  void Rotate(int direction) { m_interface->Rotate(direction); }
+  int GetInput() { return m_interface->GetInput(); }
+  void Die() { m_interface->Die(); }
+
+  // Accessors -- these are used to gain access to private data.
+  const Genome& GetGenome() const { return m_genome; }
+  cHardwareBase& GetHardware() { return *m_hardware; }
+  cPhenotype& GetPhenotype() { return m_phenotype; }
+  cGenotype* GetGenotype() { return m_genotype; }
+};
+
+ + +

 

+

Style and Syntax Guide

+ +

+Don't worry too much about how the syntax works. The code presented above +is a definition of a class in C++. It is broken into two parts; one labeled +private: for those portions of the definition that can only +be interacted with from within the class, and another labeled public: +which defines the interface to the outside. In this case, we've made all +of the variables private and the methods public. +

+

+A variable is defined by a description of the type of variable (such +a cPhenotype) and then the name of this particular instance +of the variable. In this case, since organisms only have one phenotype, +we called it merely m_phenotype. Not that because this +variable is a member of cOrganism instances, it is +prefixed with 'm_'. +

+ +

+Methods are slightly more complex. The declaration of a method starts with the +type of data the method returns (such as int for integer), or else +lists void if there is no return value. Then the method name is +given, followed by a set of parenthesis (which are what indicates to C++ that +you are declaring a method). Inside of those parentesis, can be +arguments, which are variables that must be given to the +method in order for it to operate correctly. The declaration can stop at this +point (ending in a semi-colon) if the method body is defined +elsewhere. The body of the method is the sourcecode that details how the method +operates, and can be included immediately after the declaration (within braces) +or be placed elsewhere in the code. Typically short method bodies are included +in the class definition, while longer ones are placed outside of it. A method is +performed on an object, by listing the object name, followed by a dot ('.'), and +then the name of the method to be called with all necessary arguments included. +This is explained further below. +

+

+The C++ language will accept variable names, class names, and method names of +any alpha-numeric sequence as long as all names begin with a letter. The only +other character allowed in a name is the underscore ('_'). To make reading code +easier, we have adopted certain conventions. +

+ +
+
an_example_variable
+
+ Variable names (including object names) are always all in lowercase + letters, with individual words separated by underscores. Variables are + either user-defined classes, numbers (integers, boolean values, floating + point numbers, etc.) or characters (single symbols)
+ +
ExampleMethod
+
+ Method names always have the first letter of each word capitalized, with the + remainder of the word in lowercase. The one exception to this is Constructors + and Destructors, which must have the same name as the class (see below). +
+
cExampleClass
+
+ Classes use a similar format to methods, but always begin with a single, + lowercase 'c'. Some other specialized types also used this format, but with a + different initial letter. For example, an initial 't' indicates a template, + which is a special type of class. +
+
CONSTANT_VALUE
+
+ Any constant values (that is, numerical values that will never change + during the course of the run) are given in all upper-case letters, with + individual words separated by underscores. +
+
+ +

+Different software projects will each use their own style conventions; these +are the ones you'll end up working with in Avida. Some exceptions do exist. +For example, the C++ language itself does not follow many style rules; +built-in C++ names are all lowercase letters, regardless of what they +represent. For more details, including spacing and other code formatting +standards you must follow in Avida, see the +Coding Standards. + + +

 

+

Description of Data Elements

+ +

+The section labeled private above lists those data that are unique +to each organism; these are objects and pointers that exist inside of +an organism object. First, m_genome keeps +the initial state of the organism. Since we never want this genome to change +over the organism's life, we place a const directive in front of +it. The const command exists so that C++ knows to warn the +programmer if they accidentally try to change an object (or variable) that +is not supposed to be altered. +

+

+The internal m_phenotype object is used to +record the behaviors and abilities that the organism demonstrates during its +life. This class has variables to track everything from the tasks performed to +the gestation time of the organism and the number of offspring it has ever +produced. The m_interface allows an +organism to communicate with the environment (either the +cPopulation or the +cTestCPU) that it is part of. This is used, +for example, when an organism is ready to finish replicating and needs its +offspring to be placed into the population. If an organism is being run on a +test CPU rather than in a proper population object, then this interface will +cause the statistics about offspring to be recorded for later use instead of +activating it. +

+

+Next, we have two pointers. A pointer is a value that +represents ("points to") a location in the physical memory of the computer. A +pointer can be identified by the asterisk ('*') that follows the type name. The +code "cGenotype* genotype" indicates that the variable +genotype points to a location in memory +where an object of class cGenotype is +stored. In this case, all of the organisms that are of a single genotype all +point to the same cGenotype object so that the genotypic information +is accessible to all organisms that may need to make use of it. +

+

+The final data element is m_hardware, a +pointer to an object of type cHardwareBase. +This variable is a pointer for a different reason than the genotype. Where a +single genotype is shared by many different organisms, each organism does +possess its own hardware. However, Avida supports more than one type of +hardware, where any of them can be at the other end of that hardware pointer. +The cHardwareBase class is used as an interface to the actual hardware that is +used. This is explained in more detail later in the section on inherited +classes. For the moment, the key idea is that a pointer can sometimes point to +a general type of object, not just those of a very specific class. +

+ + +

 

+

Description of Methods

+ +

+Class descriptions (with limited exceptions) must contain two specific +methods called the constructor and the +destructor. The constructor always has the same name as the +class (it's called cOrganism(...) in this +case), and is executed in order to create a new object of that class. The +arguments for the constructor must include all of the information required to +build on object of the desired class. For an organism, we need the world +object within which the organism resides, the current execution context, and +perhaps most importantly the genome of the organism. The method is not defined +here, only declared. A declared method must be defined +elsewhere in the program. All methods must be, at least, declared in the class +definition. Note that if there are many ways to create an object, multiple +constructors are allowed as long as they take different inputs. +

+

+Whereas the constructor is called when an object is created, the destructor +is called when the object is destroyed, whereupon it must do any cleanup, +such as freeing allocated memory (see the section on memory management +below). The name of a destructor is always the same as the class name, +but with a tilde ('~') in front of it. Thus, the cOrganism's destructor +is called ~cOrganism(). A destructor can +never take any arguments, and there must be only one of them in a class +definition. +

+

+The next group of five methods are all called when an organism needs +to perform some behavior, which in all of these cases involves it interacting +with the population. For example, if you need to know at whom an organism +is facing, you can call the method +GetNeighbor() +on it, and a pointer to the neighbor currently faced will be returned. +Likewise, if you need to kill an organism, you can call the method +Die() on it, and it will be terminated. +Since each of these require interaction on the population level, the population +itself takes care of the bulk of the functionality. +

+

+The 'Accessors' are methods that provide access to otherwise private +data. For example, the method GetGenome() +will literally pass the genome of the organism to the object that calls it. In +particular, the hardware object associated with an organism will often call +GetPhenotype() in order to get the current +state of the organism's phenotype and update it with something new the organism +has done. Several things to take note of here. In the first three accessors, +the name of the class being returned is followed by an ampersand ('&'). +This means that the actual object is being passed back, and not just a copy of +all the values contained in it. See the next section on pointers, references, +and values for more information about this. Also, in the very first accessor, +the keyword const is used twice. The first time is to say that +the object being passed out of the method is constant (that is, the programmer +should be warned if somewhere else in the code it is being changed) and the +second time is to say that the actions of this method will never change +anything about the object they are being run on (that is, the object is being +left constant even when the method is run.) The net effect of this is that an +object marked const can only have const methods run on it. The compiler will +assume that a non-const method being run will make a change to the object, and +is therefore an error. +

+

+This section has contained information about a particular C++ class found +in Avida. The next sections will more generally explain some of the +principles of the language. If you haven't already, now might be a good +time to take a deep breath before you dive back in. +

+ + +

 

+

Pointers, References, and Values

+ +

+The three ways of passing information around in a +C++ program is through sending a pointer to the location of that information, +sending a reference to it, or actually just sending the value of the information. +For the moment, lets consider the return value of a method. Consider +the three methods below: +

+
+  Genome GetGenomeValue();
+  Genome* GetGenomePointer();
+  Genome& GetGenomeReference();
+
+

+These three cases are all very different. In the first case +(Pass-by-Value), the value of the genome in question is +returned. That means that the genome being returned is analyzed, and the exact +sequence of instruction in it are sent to the object calling this method. Once +the requesting object gets this information, however, any changes made to it do +not affect the original genome that was copied. The second case +(Pass-by-Pointer),only a few bytes of information are returned +that give the location in memory of this genome. The requesting object can then +go and modify that memory if it chooses to, but it must first 'resolve' the +pointer to do so. Finally, the last case (Pass-by-Reference) +actually passes the whole object out. It is used in a very similar way to +pass-by-value, but any changes made to the genome after it is passed out will +affect the genome in the actual organism itself! Pass-by-reference does not +add any new functionality over pass-by-pointer, but in practice it is often +easier to use. +

+ + +

 

+

Memory Management

+ +

+Memory management in C++ can be as simple or complicated as the programmer +wants it to be. If you never explicitly allocate a chunk of memory, than +you never need to worry about freeing it up when you're done using it. +However, there are many occasions where a program can be made faster or +more flexible by dynamically allocating objects. The command +new is used to allocate memory; for example if +you wanted to allocate memory for a new genome containing 100 instructions, +you could type: +

+
+  Genome* created_genome = new Genome(100);
+
+

+The variable created_genome is defined as a pointer to a memory location +containing a genome. This is assigned the location of the newly allocated +genome in memory, which is the return value of the new command. +The Genome constructor (called with new) takes as an argument a single number +that is the sequence length of the genome. +

+

+Unfortunately, C++ won't know when we're done using this genome. If we +need to create many different genomes and we only use each of them once, +our memory can rapidly fill up. So, we need tell the memory management +that we are finished with the current object. Thus, when we're done using +it, we type: +

+
+  delete created_genome;
+
+

+And the memory pointed to by the created_genome +variable will be freed up. +

+

+An excellent example of when allocation and freeing of memory is employed +in Avida is with the genotype. Every time a new genotype is created during +evolution, Avida needs to allocate a new object of class cGenotype. During +the course of a run, millions of genotypes may be created, so we need to be +sure to free genotypes whenever they will no longer be needed in the run. +

+ + +

 

+

Inherited Classes

+ +

+One of the beauties of C++ is that well written code +is inherently very reusable. As part of that, there is the concept +of the class inheritance. When a new class is built in C++, +it is possible to build it off of an existing class, then referred to as +a base class. The new derived +class will have access to all of the methods in the base class, and can +overload them; that is, it can change how any of those +methods operate. +

+

+For example, in the Avida scheduler, we use a class called +cSchedule to determine which organism's +virtual CPU executes the next instruction. Well, this cSchedule object is not +all that clever. In fact, all that it does is run through the list of +organisms that need to go, lets them each execute a single instruction, and +then does it all over again. But sometimes we need to make some organisms +execute instructions at a faster rate than others. For that reason, there are +several derived classes, including +cIntegratedSchedule, which takes in a merit +value for each organism, and assigns CPU cycles proportional to that merit. +Since this new class uses cSchedule as its base class, it can be dynamically +plugged in during run time, after looking at what the user chooses in the +configuration file. +

+

+If a method is not implemented in a base class (left to be implemented in the +derived classes) it is called an abstract method. If a base +class does not implement any of its methods and is only used in order +to specify what methods need to be included in the derived classes, it is +referred to as an abstract base class (or sometimes an +interface class or protocol) and is used +simply as a method contract for derived classes. An example in Avida where this +is used is the organism interface with the environemnt. The class +cOrgInterface is an abstract base class, +with cPopulationInterface and +cTestCPUInterface as derived classes. This +organization allows for organism objects to interact with both the population +and the test environment, without having to write separate code for each. +

+ + +

 

+

Other C++ Resources:

+ + \ No newline at end of file diff --git a/docs/documentation/Development-|-Tutorial-|-Environment.md b/docs/documentation/Development-|-Tutorial-|-Environment.md new file mode 100644 index 0000000..0f355be --- /dev/null +++ b/docs/documentation/Development-|-Tutorial-|-Environment.md @@ -0,0 +1,268 @@ +

+The environment source code consists of several main components: resources, +reactions, and task triggers, plus the libraries that maintain each of these. +

+ + +

 

+

Task Entries

+ +

+A task library is composed of a collection of entries, each of which fully +describes a single task that can be used to trigger reactions. +

+
+typedef double (cTaskLib::*tTaskTest)(cTaskContext*) const;
+
+class cTaskEntry {
+private:
+  cString m_name;  // Short keyword for task
+  cString m_desc;  // For more human-understandable output...
+  int m_id;
+  tTaskTest m_test_fun;
+  cString m_info;  // extra info (like the string or whatever to match)
+  
+public:
+  cTaskEntry(const cString& name, const cString& desc, int in_id, tTaskTest test_fun, const cString& info);
+    : m_name(name), m_desc(desc), m_id(in_id), m_test_fun(test_fun), m_info(info)
+  {
+  }
+  ~cTaskEntry() { ; }
+
+  const cString& GetName() const { return m_name; }
+  const cString& GetDesc() const { return m_desc; }
+  const int GetID() const { return m_id; }
+  const tTaskTest GetTestFun() const { return m_test_fun; }
+  const cString& GetInfo() const { return m_info; }
+};
+
+ +

+Task entries are very straight-forward. They consist of a name, a description, +a unique ID number, and a method from the task library (cTaskLib) that they +are associated with. This method looks at the inputs the organism has taken +in, the values it has output, and returns a number between 0.0 and 1.0 +representing how well the task was performed. Currently, all task tests will +return an exact zero or one, but fractions are possible if there +is a quality component associated with the task. +

+ + +

 

+

Task Libraries

+ +

+Here is an abridged version of the task library class that manages all of the +individual entries: +

+ +
+class cTaskLib {
+private:
+  Apto::Array<cTaskEntry*> task_array;
+
+public:
+  int GetSize() const { return task_array.GetSize(); }
+
+  cTaskEntry* AddTask(const cString& name, const cString& info);
+  const cTaskEntry& GetTask(int id) const;
+
+  void SetupTests(cTaskContext& ctx) const;
+  inline double TestOutput(const cTaskEntry& task, cTaskContext* ctx) const;
+
+private:
+  double Task_Echo(cTaskContext* ctx) const;
+  double Task_Add(cTaskContext* ctx) const;
+  double Task_Sub(cTaskContext* ctx) const;
+
+  double Task_Not(cTaskContext* ctx) const;
+  double Task_Nand(cTaskContext* ctx) const;
+  double Task_And(cTaskContext* ctx) const;
+  // ... And a whole bunch more ...
+
+};
+
+ +

+The task library contains an array of task entries that define all of the +rewarded (or otherwise acted upon) tasks in an environment. +

+

+The TestOutput() method can only be run with +as cTaskContext object that has been initialized +with the SetupTests method. It will test the +specific task passed in and return the 0.0 - 1.0 quality measure of how well +that task was done with the most recent output. +

+ +

+Below is a sample task-tester implementation: + +

+double cTaskLib::Task_Add(cTaskContext* ctx) const
+{
+  const int test_output = ctx->output_buffer[0];
+  for (int i = 0; i < ctx->input_buffer.GetNumStored(); i++) {
+    for (int j = 0; j < i; j++) {
+      if (test_output == ctx->input_buffer[i] + ctx->input_buffer[j]) return 1.0;
+    }
+  }
+  return 0.0;
+}
+
+ +

+This case tests to see if the organism has performed an addition operation. +It compares all pairs of inputs summed together against the most recent +output of the organism. If there is a match a full reward (1.0) is given. +If no match is found, no reward is given (0.0). +

+ +

+The SetupTests method performs some +precomptution for all of the logic tasks, creating the value +logic_id within the task context. The +logic_id has 256 possible values, each of which +can only be associated with a single logic task. These tests look more like: +

+ +
+double cTaskLib::Task_AndNot(cTaskContext* ctx) const
+{
+  const int logic_id = ctx->logic_id;
+  if (logic_id == 10 || logic_id == 12 || logic_id == 34 ||
+      logic_id == 48 || logic_id == 68 || logic_id == 80) return 1.0;
+  return 0.0;
+}
+
+ +

+If the logic ID is on the list, the task has been done, otherwise it hasn't. +In each case, the outside world needs to request a test of which tasks have +been performed, and the library just replied with a numerical answer. +

+ + +

 

+

Building a Reaction

+ +

+The reaction class keeps track of all of the information associated with +a single possible environmental reaction. Each reaction must have a unique +name and a unique numerical ID associated with them. In addition to those +data, a reaction object also has a task that acts as its trigger, a list of +other requisites that must be met for the trigger to work, and a list of +processes that will occur if the reaction goes off. The cReaction object +acts a a single place to store all of this information. +

+ + +

 

+

Resources

+ +

+Resources are a little more complicated than task entries to manage +and understand. An object of type cResource +contains 19 pieces of data, and the associated accessors. Like all of the +other individual units we have discussed, resources have a unique +name and numerical +id. For all resource we store the quantities +associated with their inflow, +outflow, and +initial count (each stored as a +double) as well as the geometry of that resource. + +

+For spatial resources we need to be able to describe how a resource +exists in space so we store data for: +

    +
  • + inflowX1, + inflowX2, + inflowY1, and + inflowY2 to describe a rectangle where + resources flow in. +
    • +
  • + outflowX1, + outflowX2, + outflowY1, and + outfowY2 for a rectangle where resources + flow out. +
    • +
  • + cell_list is a list of individual cells with + their own initial, inflow and outflow values. +
  • + xdiffuse and + ydiffuse describe how fast resources will + flow from cells of higher amounts of that resource to cells with + lower amounts of that resource. +
    • +
  • + xgravity and + ygravity describe the preferential flow of + resource in a given direction. +
    • +
+

+This class describes the dynamics of a resource, not its current count +(since, for example, we might want local resources where each cell +would have its own count). However, every time a +resource is needed, any changes in its quantity from the last time it was +used can be calculated using these numbers. +

+ + +

 

+

Tying it all together: The Environment

+ +

+The cEnvironment class is used to maintain the details of how the environments +work using the classes described above and a few others. Below is an +abbreviated version of this class: +

+ +
+class cEnvironment {
+private:
+  // Keep libraries of resources, reactions, and tasks.
+  cResourceLib resource_lib;
+  cReactionLib reaction_lib;
+  cTaskLib task_lib;
+  cInstLib inst_lib;
+  cMutationRates mut_rates;
+
+public:
+  bool Load(const cString& filename);
+
+  // Interaction with the organisms
+  bool TestOutput(cAvidaContext& ctx, cReactionResult& result, cTaskContext& taskctx,
+                 const tBuffer<int>& send_buf, const tBuffer<int>& receive_buf,
+                 const Apto::Array<int>& task_count, const Apto::Array<int>& reaction_count,
+                 const Apto::Array<double>& resource_count) const;
+};
+
+ +

+The private data members include all of the libraries needed to specify +the environment, plus its mutation rates. The +Load() method takes a filename +(environment.cfg by default) and will fill out all of the libraries +in this environment. The most important feature of this class is the +TestOutput() method, which takes in all sorts +of information about the current state of the organism that has just done +an output and fills out an object of type +cReactionResult with information about what +happened. It also directly returns a bool that will indicate if there have +been any changes at all. The specific information it uses to determine +the results are the inputs the organism has taken in and the outputs it has +produced -- both needed to determine what tasks have been done, and therefore +what reactions may have been triggered. This information is encapsulated in +the task context taskctx. The organism's +previous task_count and +resource_count are also needed to determine +if the reactions requisites have been met. And finally the +resource_count available to the organisms is +needed to determine how much of each resource can be used in the reactions. +

diff --git a/docs/documentation/Development-|-Tutorial-|-Genome.md b/docs/documentation/Development-|-Tutorial-|-Genome.md new file mode 100644 index 0000000..060a8b8 --- /dev/null +++ b/docs/documentation/Development-|-Tutorial-|-Genome.md @@ -0,0 +1,161 @@ +

+This document discusses the implementation of the cInstruction and Genome classes. +

+ + +

 

+

The cInstruction Class

+ +

+This class is used to represent a single instruction within a genome. The +private portion of this class consists of a single number that uniquely +identifies the type of instruction, and the public section +has a number of helper methods that allow us to work with that number. +

+ +
+class cInstruction {
+private:
+  unsigned char m_operand;
+
+public:
+  // Constructors and Destructor...
+  cInstruction() : m_operand(0) { ; }
+  cInstruction(const cInstruction& inst) { *this = inst; }
+  explicit cInstruction(int in_op) { SetOp(in_op); }
+  ~cInstruction() { ; }
+
+  // Accessors...
+  int GetOp() const { return static_cast<int>(m_operand); }
+  void SetOp(int in_op) { assert(in_op < 256); m_operand = in_op; }
+
+  // Operators...
+  void operator=(const cInstruction& inst) { m_operand = inst.m_operand; }
+  bool operator==(const cInstruction& inst) const { return (m_operand == inst.m_operand); }
+  bool operator!=(const cInstruction& inst) const { return !(operator==(inst)); }
+
+  // Some extra methods to convert too and from alpha-numeric symbols...
+  char GetSymbol() const;
+  void SetSymbol(char symbol);
+};
+
+ +

+As stated above, the only private datum is a numerical value that identifies +this instruction. The name m_operand is the term +that is used for a command name in an assembly language. Most normal assembly +languages have both an operand and arguments associated with each full command. +In Avida, the commands have no arguments, and hence they just consist of a +single operand. The data type used for this is unsigned char. A +char is an 8 bit number, so when one is unsigned, it represents a number from 0 +to 255. As Avida is currently implemented, we are limited to 256 distinct +instructions. To the outside world, we treat the instruction operand like an +integer, so it would be easy to modify this class were we ever to need more +than 256 instructions in the set. The only reason to limit it to 8 bits +internally (rather than the 32 of an int) is to save memory when we have a very +large number of instructions throughout a population. Instructions already +make up over half of all the memory resources used by Avida. +

+

+The public methods begin with the GetOp() and +SetOp() methods, which are standard accessors. +Next, we have a collection of methods that begin with the word 'operator'. +These are used to define how the corresponding symbols should be treated +when applied to objects of this class. For example, the method +operator==() is called when we try to compare +an object of type cInstruction to another. We have full control over the +definition of this method, just like any other. +

+

+Finally, we have a pair of methods that convert instructions to and from +alphanumeric characters (symbols). These methods are used to print instructions +out in a maximally compressed format, and to load them back in. The order of +symbols used are the letters 'a' through 'z' in lowercase, followed by an +uppercase 'A' through 'Z' and finally the numbers '0' through '9'. If there +are more than 62 possible instructions, all the rest are assigned a '?' when +printed out, and cannot be read back in properly from this format. +

+ + +

 

+

The Genome class

+ +

+A genome is a sequence of instructions. The following class maintains this +sequence as an array, and provides a collection of methods to manipulate the +total construct. +

+ +
+class Genome
+{
+protected:
+  Apto::Array<cInstruction> genome;
+  int active_size;
+ 
+public:
+  Genome() { ; }
+  explicit Genome(int _size);
+  Genome(const Genome& in_genome);
+  Genome(const cString& in_string);
+  virtual ~Genome();
+ 
+  virtual void operator=(const Genome& other_genome);
+  virtual bool operator==(const Genome& other_genome) const;
+  virtual bool operator!=(const Genome& other_genome) const { return !(this->operator==(other_genome)); }
+  virtual bool operator<(const Genome& other_genome) const { return AsString() < other_genome.AsString(); }
+ 
+  cInstruction& operator[](int index) { assert(index >= 0 && index < active_size);  return genome[index]; }
+  const cInstruction& operator[](int index) const { assert(index >= 0 && index < active_size);  return genome[index]; }
+ 
+  virtual void Copy(int to, int from);
+ 
+  int GetSize() const { return active_size; }
+  cString AsString() const;
+};
+
+ +

+The protected variable genome is an array +containing an object of type cInstruction at each position. The second +variable active_size denotes the number of +instructions in this array that are currently being used. The fact that +these variables are "protected" instead of "private" means that any +class derived from Genome will also have direct +access to the variables. In particular, the class +cCPUMemory extends Genome, adding methods to +alter the array length and new variables to keep track of information about +each instruction. +

+

+Three constructors allow for a new Genome object to be specified by either a +genome length, a previously created genome, or else a string -- a sequence +of symbols representing each instruction in order. +

+

+The operators created for manipulating genomes include both assignment +(setting one genome equal to another) and comparison (testing to see if +two genomes are identical.) Additionally, there are two +operator[] methods. This means that if you +have an object of type Genome, you can index into it to retrieve a single +instruction. Thus, if the object was called initial_genome, the +statement initial_genome[15] would return the instruction at +position fifteen in the genome. This occurs by calling one of these methods +with the appropriate integer. The difference between these two operator +methods is that one of them is for mutable genomes (i.e. those that can be +modified) -- a reference to the instruction in question is returned allowing +it to be altered. The other index operator (operator[] method) is for const +genomes, which can never be changed so only the value of the instruction is +returned. +

+

+The Copy() method is a shortcut to copy memory +from one position in the genome to another. This method will later be +overloaded (that is, replaced with a newer version) by +cCPUMemory such that the proper flags will be copied, with the instruction +and others will be set to indicate the copied instruction for future tests. +GetSize() returns the length of the genome, and +AsString() returns a string who has symbols in +each position that correspond to the the instruction in the same position in +the genome. +

diff --git a/docs/documentation/Development-|-Tutorial-|-Life-Cycle.md b/docs/documentation/Development-|-Tutorial-|-Life-Cycle.md new file mode 100644 index 0000000..84224aa --- /dev/null +++ b/docs/documentation/Development-|-Tutorial-|-Life-Cycle.md @@ -0,0 +1,233 @@ +

+This document examines the details of commands directly involved in +replication. +

+ + +

 

+

1. Allocation of Offspring Memory

+ +

+The very first instruction in most heads-based organisms is h-alloc, +which will allocate space for an offspring to be placed into. If you look at +the file source/cpu/cHardwareCPU.cc, you will see that this +instruction is associated with the method +cHardwareCPU::Inst_MaxAlloc(). +What this means is that the organism will automatically allocate as much +space as it possibly can, without having to first calculate its needs. When +the organism is finished copying itself and divides off its child, any excess +allocated memory will automatically be discarded. +

+

+This Inst_MaxAlloc() method will determine the maximum amount of extra space +that an organism is allowed to allocate, and then run the Allocate_Main() +function passing in that amount. Allocate_Main is a very long method which is +mostly just check to make sure that everything going on is legal, and then +initializes the new memory that was allocated as per the configuration file: +random, default instruction, or leave as it was in the previous organism that +used it (for "necrophelia"). +

+ + +

 

+

2. Initial Self-Analysis

+ +

+Most of the initial self-analysis done on Avida organisms is with the +search instruction or one of its variants. In the heads based +instruction set, we call this h-search and associate it with the +method cHardwareCPU::Inst_HeadSearch(). +

+

+The search type instructions read in the template (series of nops) that +follows it, determine the complement template, and find that complement +elsewhere in the genome. It then sets the registers BX and CX to be the +distance to the found template and the size of that template respectively. +Finally, we place the flow control head at the end of the template found in +order to reference it later on. Obviously this last step only occurs +in the heads-based search. +

+

+The first search instruction executed by a heads organism is typically used +to locate the end of its genome. The search will place the flow-head at +the end of the genome, which the organism will use to move the write head to +this point as well. This is done with the mov-head instruction. +

+

+If the mov-head instruction is followed by a nop-C it +will move the write head to the flow head, and ideally be ready to start +copying itself into the newly allocated space for the offspring. +

+ + +

 

+

3. The Copy Loop

+ +

+The copy loop is the heart of any organism. It consists of a setup, +a copy segment to copy one or more instructions, a test segment to determine +if the loop has finished, and a 'jump' type instruction to move back to +copy the next line. +

+

+In a hand written organism, the setup is an h-search command with +no template to direct its behavior. The default when this instruction does not +have a template is to just drop the flow-head at the very next instruction, +which is what it is used for here -- it places the flow head at the beginning +of the portion of code that will actually be looped through copying each line. +

+

+The copy segment is typically just a single h-copy instruction +that will read in an instruction from the location of the read-head, and write +it out to the location of the write-head. It will then advance both heads to +the next positions in the genomes. Take a look at the source code for the +method cHardwareCPU::Inst_HeadCopy(). +

+

+The first thing that happens in this method is the variables +read_head, +write_head, and +cpu_stats are setup as references to the +appropriate objects in the hardware and organism (that is, any modifications +to these references change the actual objects, not just a local copy of them). +This is so that we have easy to use variables locally for those objects that +we are working with. The read_head and write_head are then adjusted to make +sure they are in a legal position on the genome (if, for example, the last +instruction changed the organism's size, the heads might no longer be +pointing to memory that still exists). +

+

+Next, the instruction at the read head is recorded in the variable +read_inst, and we test to see if this should +be mutated to some other value. If a mutation does occur, we change the +read_inst variable to a random value, increment the mutation count, and mark +flags at the instruction position of the write head to denote the mutation. +After we determine what instruction was read (be it a correct reading or not), +we call the ReadInst() method, which is simply +used to keep track of the most recent template copied. This template is used +to help detect the end of the organism, which we shall discuss in a moment. +

+

+Finally, we collect the statistics that another copy command was executed +in this organism, finish the write by placing this instruction at the position +of the write head (and setting its flag as being a copied instruction) and +then advancing both heads to their next positions. +

+

+After an organism executes one of these copies it has to test to see if it +is done copying itself. The heads based organisms will typically do this +with the aid of the if-label instruction, which tests to see if +the most recent label copied is the complement of the one that follows it. +If so, it will execute the next instruction (often a divide), otherwise it +will skip that next instruction and execute a mov-head that will +jump the instruction pointer back to the flow head that was placed at the +beginning of the copy loop. It will continue this copy-test-jump cycle +until all the lines have been copied. +

+

+A common adaptation is "unrolling the loop". +In the hand-written version discussed above, each instruction must have +three instructions executed to copy it: h-copy, +if-label, and mov-head. But what if a second +h-copy command were inserted after the first? Now the program +would be one line longer, so it would have more to copy, but each time +through the loop would now copy two instructions while executing four -- +that means that on average only two instructions need be executed to copy +one. A *huge* savings. The main drawback to the organism is that its +length will need to be a multiple of two, or else the test to see if it is +finished won't occur at the proper time. This loop unrolling becomes less +and less beneficial each time the organism does it, so it won't go completely +out of control. +

+ + +

 

+

4. Dividing off the Child

+ +

+When an organism finishes copying itself, it needs to divide off its +child using a divide command. In the heads based instruction set, this is +the h-divide command which calls the +cHardwareCPU::Inst_HeadDivide() +method. +

+

+This method will use the read head to determine the starting location of the +offspring, and the write head to determine its end. This is logical because +these are the locations that the heads should be in right after the copy loop +has finished. Everything after the write head is cut off and discarded as +"extra lines". This information is passed into the Divide_Main method +which does the bulk of the work for divide (and is called by all of the various +divide instructions in all of the sets). +

+

+The cHardwareCPU::Divide_Main() +method is therefore what we are most interested in. It begins by calculating +the size of that child that would result from the divide point and the +extra_line count that were passed into it, and runs +Divide_CheckViable() to make sure that all of +these values are legal (that is that both parent and child are reasonable +sizes for organisms, and reasonable sizes in relationship to each other -- for +definitions of reasonable as found in the configuration file). If any of +them are not legal, the method returns false. +

+

+From this point on, we know the divide is legal, so we just need to process +it. We create a variable called child_genome, +which we use to construct the child genome. We use a reference to a Genome +object inside of the organism so that this child genome is attached to its +parent organism and will be easily accessible from other places where it will +be needed later. We're not going to be doing all of the work on it right in +this method. We initialize the child genome to the section of the parents +genome that was created for it. We then run +Resize() on the parent genome to get +rid of all of this extra space (both child and extra lines). +

+

+The Divide_DoMutations() method will test and +(if needed) process any divide mutations that may occur. There are many of +them, so this method is quite long. It is followed by +Divide_TestFitnessMeasures(), which will run the +offspring through a test CPU for special options that may be set in the +genesis file (such as mutation reversions). Obviously this is very processor +intensive since it would occur with every birth, so tests are only performed +if required. Both of these methods are left to the reader to step through +themselves. +

+

+If we are using extra costs associated with the first time instructions are +used, those costs a reset now that a divide has occurred, and must be paid for +again on the next divide cycle. +

+

+After a divide, we mark that we no longer have a mal (Memory ALlocation) +active. If the parent is reset (i.e., we have two offspring, not a parent +and child) we need to make sure not to advance the IP of the parent. The +reset parent has its IP placed at the beginning of its genome, and we want +to leave it there to execute the very first instruction. +

+

+Finally, we tell the organism to activate the divide and do something with +the child. Give the child to the population (or the test CPU as the case +may be) to be dealt with, and reset the parent if we're splitting into two +offspring. +

+ + +

 

+

5. Other Bits

+ +

+In the description of this life-cycle, one issue that has not been discussed is +where these organisms would perform their computations. In truth, there isn't +a fixed time other than it must be before the divide occurs, since merit is +recalculated on a divide. In practice it will typically be placed right before +the copy loop, but there are plenty of exceptions. +

+

+Ideally, in the longer term, an organism's life will be composed of much +more than just replication and computations -- they will have to interact with +each other and have more interactions with the environment. In a +multi-threaded model, organisms will be doing many activities at the same +time. +

\ No newline at end of file diff --git a/docs/documentation/Development-|-Tutorial-|-Task-Checklist.md b/docs/documentation/Development-|-Tutorial-|-Task-Checklist.md new file mode 100644 index 0000000..28248d3 --- /dev/null +++ b/docs/documentation/Development-|-Tutorial-|-Task-Checklist.md @@ -0,0 +1,108 @@ +

+This document discusses how to implement your own tasks to use as triggers +for reactions in the environment. +

+ + +

 

+

1. Build the prototype of the method that will be used to test the new task

+ +

+For this step, you will be editing the task library found in the files +cTaskLib.cc and cTaskLib.h in the directory +source/main/. Start by adding the prototype of your new test +function to the cTaskLib class in the header file. The data that will be +tested is all stored within task context that is passed into this function. +This function will output a double that represents the quality with +which the task is performed. This is a number between 0 and 1 that +determines the fraction of the bonus that should be received. For tasks that +are either successful or not, this will only return 0.0 or 1.0. +

+

+For example, if we were going to create a task that tests if the organisms +could double one of their inputs, we might call that task 'times2'. We would +then add the line to this file: +

+
+double Task_Times2(cTaskContext& ctx) const;
+
+ +

+If possible, place it near other tasks of the same type. In this case, +I choose to place it directly after Task_Echo(), since this is also an +easy task for the organisms to perform. +

+ + +

 

+

2. Build the body of the method that will be used to test the new task

+ +

+We next go into the code (cTaskLib.cc) file, and add the body of our +new method. We search for cTaskLib::Task_Echo(), since our new prototype +followed this method in the header file, and place the body of our function +immediately after it. +

+ +
+double cTaskLib::Task_Times2(cTaskContext& ctx) const
+{
+  const tBuffer<int>& input_buffer = ctx.GetInputBuffer();
+  const int test_output = ctx.GetOutputBuffer()[0];
+  const int input_size = ctx.GetInputBuffer().GetNumStored();
+  for (int i = 0; i < input_size ; i++)
+  {
+    if ( test_output == 2 * input_buffer[i])
+    {
+      return 1.0;
+    }
+  }
+  return 0.0;
+}
+
+ +

+The most recent output is always placed at the beginning of the output +buffer, so we store it in the variable +test_output to compare it against all of the +different inputs. We then have a for-loop that goes from 0 to the number +of inputs stored in the input buffer. Inside the body of the loop, we +test for each input if twice that input is equal to the output. If so, +then the task was successful and we return a 1.0. If all of the tests +fail and we exit the loop, then we return a 0.0. +

+

+These test methods should be carefully written so that they run as fast +as possible. In particular, if a task requires that an output be +compared to multiple inputs at a time (i.e., the tasks Add or Subtract), +then this can become combinartoically explosive. For the moment, we +keep control on this problem by only allowing three different inputs +in the input buffer, but in the future this number may need to become +higher. +

+ + +

 

+

3. Attach our new method to the name of its trigger

+ +

+This next step is also done in the code file, inside the +cTaskLib::AddTask() +method. Again, we want this to be in the same place, so we locate the +task 'echo' that its supposed to follow, and add in the new line. +

+ +
+else if (name == "times2")
+  NewTask(name, "Times2", &cTaskLib::Task_Times2);
+
+ +

+This line will attach the name to the description "Times2" (which +could have been a little more detailed, but should be 40 characters or less) +as well as the function that should be called when that name is listed as a +trigger to a reaction. +

+

+You are now ready to use your task! +

diff --git a/docs/documentation/Divide-settings.md b/docs/documentation/Divide-settings.md new file mode 100644 index 0000000..bf94c14 --- /dev/null +++ b/docs/documentation/Divide-settings.md @@ -0,0 +1,38 @@ +

These place limits on when an organism can successfully issue a divide command to produce an offspring.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OFFSPRING_SIZE_RANGEThis is the maximal difference in genome size between a parent and offspring. The default of 2.0 means that the genome of the child must be between one-half and twice the length of the parent. This it to prevent out-of-control size changes. Setting this to 1.0 will ensure fixed length organisms (as long as you also change the other settings detailed in How to Set Up Fixed-Length Organisms).
MIN_COPIED_LINES
MIN_EXE_LINES 		These settings place limits on what the parent must have done before the offspring can be born; they set the minimum fraction of instructions that must have been copied into the offspring (vs. left as default) and the minimum fraction of instructions in the parent that must have been executed. If either of these are not met, the divide will fail. These settings prevent organisms from producing pathological offspring. In practice, either of them can be set to 0.0 to turn them off.
REQUIRE_ALLOCATEIs an allocate required between each successful divide (in virtual hardware types where allocate is meaningful)? If so, this will limit the flexibility of how organisms produce children (they can't make multiple copies and divide them off all at once, for example). But if we don't require allocates, the resulting organisms can be a lot more difficult to understand.
REQUIRED_TASKThis is a bit of a hack. It allows the user to set the ID number for a task that must occur for a divide to be successful. At -1, no tasks are required. Ideally, this should be incorporated into the environment configuration file. NOTE: A task can fire without triggering a reaction. To add a required reaction see below.
IMMUNITY_TASKAllows user to set the ID number for a task which, if it occurs, provides immunity from the required task (above) -- divide will proceed even if the REQUIRED_TASK is not done if IMMUNITY_TASK is done. Defaults to -1, no immunity task present.
REQUIRED_REACTIONAllows the user to set the ID number for a reaction that must occur for a divide to be successful. At -1, no reactions are required.
IMMUNITY_REACTIONAllows the user to set the ID number for a reaction that, if it occurs, provides immunity from the required reaction (above) -- divide will proceed even if the REQUIRED_REACTION has not been performed as long as the IMMUNITY_REACTION has been performed. Defaults to -1, no immunity reaction present.
REQUIRE_EXACT_COPYRequires the offspring to be an exact copy of the parent -- before divide mutations are imposed. At first glance this setting looks very similar to the STERILIZE_UNSTABLE setting in the Mutation Reversion group of settings. However, REQUIRE_EXACT_COPY allows any kind of divide mutation (see Mutation Settings)-- point, insertion, deletion, slip, etc. It does not allow before-divide mutations such as copy mutations. On the other hand, STERILIZE_UNSTABLE allows any kind of mutation, as long as the organism would be able to perfectly copy itself in the absence of mutations.
+

Many other requirements can be imposed. See avida.cfg for MIN_GENOME_SIZE, MAX_GENOME_SIZE, REQUIRE_SINGLE_REACTION, REQUIRED_BONUS, REQUIRED_RESOURCE, REQUIRED_RESOURCE_LEVEL, REQUIRED_PRED_HABITAT, REQUIRED_PRED_HABITAT_VALUE, IMPLICIT_REPRO_BONUS, IMPLICIT_REPRO_CPU_CYCLES, IMPLICIT_REPRO_TIME, IMPLICIT_REPRO_END, and IMPLICIT_REPRO_ENERGY.

diff --git a/docs/documentation/Energy-model-configuration.md b/docs/documentation/Energy-model-configuration.md new file mode 100644 index 0000000..52ae1d4 --- /dev/null +++ b/docs/documentation/Energy-model-configuration.md @@ -0,0 +1,101 @@ +

Overview

 +

+The energy model provides an organism with a metabolic rate, which is proportional to its stored energy (shown below). + +An organism with a higher metabolic rate will pay more energy to execute instructions than one with a lower rate. + +An organism must pay both virtual CPU cycle and energy costs to execute instructions. + +As instructions are executed the organism's stored energy level is reduced. + +Energy can be taken up by the organism when it completes a task, among others. +

+ +
+Metabolic Rate = Stored Energy / NUM_INST_EXC_BEFORE_0_ENERGY +
+ +

Settings

 +

+The settings below are defults from avida.cfg +

+### ENERGY_GROUP ###
+# Energy Settings
+ENERGY_ENABLED 0                       # Enable Energy Model. 0/1 (off/on)
+ENERGY_GIVEN_ON_INJECT 0               # Energy given to organism upon injection.
+ENERGY_GIVEN_AT_BIRTH 0                # Energy given to offspring upon birth.
+FRAC_PARENT_ENERGY_GIVEN_AT_BIRTH 0.5  # Fraction of perent's energy given to offspring.
+FRAC_ENERGY_DECAY_AT_BIRTH 0.0         # Fraction of energy lost due to decay during reproduction.
+NUM_INST_EXC_BEFORE_0_ENERGY 0         # Number of instructions executed before energy is exhausted.
+ENERGY_CAP -1                          # Maximum amount of energy that can be stored in an organism.
+                                       # -1 means the cap is set to Max Int
+APPLY_ENERGY_METHOD 0                  # When should rewarded energy be applied to current energy?
+                                       # 0 = on divide
+                                       # 1 = on completion of task
+                                       # 2 = on sleep
+FRAC_ENERGY_TRANSFER 0.0               # Fraction of replaced organism's energy take by new resident
+LOG_SLEEP_TIMES 0                      # Log sleep start and end times. 0/1 (off/on)
+                                       # WARNING: may use lots of memory.
+
+

+ +

Description of Settings

 +ENERGY_ENABLED +

+Flag that disables/enables the us of the energy model. + +0 = off, 1 = on +

+ +ENERGY_GIVEN_ON_INJECT +

+How much energy is given to an injected organism. + +This number should be large enough to sustain the population until it can gather its own energy through tasks, etc.. +

+ +ENERGY_GIVEN_AT_BIRTH +

+How much energy is given to an organism when it is born. +

+ +FRAC_PARENT_ENERGY_GIVEN_AT_BIRTH +

+Fraction of the parent(s) energy which is taken from the parent and given to the offspring at birth. +

+ +FRAC_ENERGY_DECAY_AT_BIRTH +

+Fraction of energy that decays on birth. +

+ +NUM_INST_EXC_BEFORE_0_ENERGY +

+Number of instructions an organism can execute before it runs out of energy assuming no new energy. + +Note: if instructions have energy costs > 0 then this options needs to be altered accordingly. +

+ +ENERGY_CAP +

+Maximum amount of energy that can be stored in an organism. +

+ +APPLY_ENERGY_METHOD +

+Specifies when newly received energy is applied to the organism energy store and metabolic rate. + +Note: the sleep instruction can also be used as an eat instructions if needed. +

+ +FRAC_ENERGY_TRANSFER +

+Fraction of a replaced organism's energy transfered to the replacing organism. +

+ +LOG_SLEEP_TIMES +

+Logs start and end times, in updates, of all executions of the sleep instruction. + +Note: can use a lot of memory. +

diff --git a/docs/documentation/Environment-file.md b/docs/documentation/Environment-file.md new file mode 100644 index 0000000..de9d10f --- /dev/null +++ b/docs/documentation/Environment-file.md @@ -0,0 +1,902 @@ +

+This is the setup file for the task/resource system in Avida. +

+

+Six main keywords are used in this file, RESOURCE, GRADIENT_RESOURCE, REACTION, CELL, MUTATION, and SET_ACTIVE. Their formats are: +

+
+  RESOURCE  resource_name[:options]  {resource_name ...}
+  GRADIENT_RESOURCE  gradient_resource_name[:options]  {gradient_resource_name ...}
+  REACTION  reaction_name  task  [process:...]  [requisite:...]
+  CELL resource_name:cell_list[:flow]
+  MUTATION name trigger scope type rate
+  SET_ACTIVE type name new_status(default=true)
+
+ +

Resources

+

+All entries on a resource line are names of individual resources. Resources can have a global quantity depletable by all organisms or can have quantities that vary from cell to cell. The resource name infinite is used to refer to an undepletable resource. There are two basic commands to set up a general resource: RESOURCE and CELL. In addition, GRADIENT_RESOURCE is a specific instance of RESOURCE which allows the user to specify a cellular distribution of quantities that change (aka move) over time in an Avida run. +

+ +

RESOURCE Command

+ +

The syntax for the Resource command is:

+ + 
RESOURCE resource_name[:options]  {resource_name ...}
+ +
+

+Where resource_name is a unique name of the resource. This name may be used by the CELL command to further define the resource or in the REACTION to define which resource is consumed/created +by a reaction. +

+

+Where options is a colon delimited list of factors that modify the +resource. The following chart specifies these options. +

+
+
+

 

+

Table 1: Resources Options

+

+(blue variables used for all resources +while red variables are only used for +spatial resources) +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ArgumentDescriptionDefault
inflow + The number of units of the resource that enter the population over + the course of an update. For a global resource this inflow + occurs evenly throughout the update, not all at once. For a + spatial resource this inflow amount is added every update + evenly to all grid cells in the rectangle described by the + points (inflowx1,inflowy1) and (inflowx2,inflowy2). + 0
outflow + The fraction of the resource that will flow out of the population + each update. As with inflow, this happens continuously over the + course of the update for a global resource. In the case of a + spatial resource the fraction is withdrawn each update from + each cell in the rectangle described by the points + (outflowx1,outflowy1) and (outflowx2,outflowy2). + 0.0
initial + The initial abundance of the resource in the population at the + start of an experiment. For a spatial resource the initial + amount is spread evenly to each cell in the world grid. + 0
geometry + The layout of the resource in space.
+ global -- the entire pool of a resource is + available to all organisms
+ grid -- organisms can only access resources in + their grid cell. Resource can not flow past the edges of the + world grid. (resource will use spatial parameters)
+ torus -- organisms can only access resources in + their grid cell. Resource can flow to the opposite edges of the + world grid. (resource will use spatial parameters) + 		global
deme + Is this resource going to be used by a deme. (True or + False) + + false +
energy + Is this an energy resource. The energy model must be used. + (True or False) + + false +
inflowx1 + Leftmost coordinate of the rectangle where resource will flow + into world grid. If not specified but an inflow rate is specified, + an x-coordinate will be determinstically assigned. + 0
inflowx2 + Rightmost coordinate of the rectangle where resource will flow + into world grid. If not specified, inflowx1's value will be used. + 0
inflowy1 + Topmost coordinate of the rectangle where resource will flow + into world grid. If not specified but an inflow rate is specified, + a y-coordinate will be determinstically assigned. + 0
inflowy2 + Bottommost coordinate of the rectangle where resource will flow + into world grid. If not specified, inflowy1's value will be used. + 0
outflowx1 + Leftmost coordinate of the rectangle where resource will flow + out of world grid. + 0
outflowx2 + Rightmost coordinate of the rectangle where resource will flow + out of world grid. If not specified, outflowx1's value will be used. + 0
outflowy1 + Topmost coordinate of the rectangle where resource will flow + out of world grid. + 0
outflowy2 + Bottommost coordinate of the rectangle where resource will flow + out of world grid. If not specified, outflowy1's value will be used. + 0
xdiffuse + How fast material will diffuse right and left. This flow + depends on the amount of resources in a given cell and amount in + the cells to the right and left of it. (0.0 - 1.0) + 1.0
xgravity + How fast material will move to the right or left. This + movement depends only on the amount of resource in a given cell. + (-1.0 - 1.0) + 0
ydiffuse + How fast material will diffuse up and down. This flow + depends on the amount of resources in a given cell and amount in + the cells above and below it. (0.0 - 1.0) + 1.0
ygravity + How fast material will move to the up or down. This + movement depends only on the amount of resource in a given cell. + (-1.0 - 1.0) + 0
+

 

+
+ +

+An example of a RESOURCE statement that begins a run with a fixed amount of the +(global) resource in the environment, but has no inflow or outflows is: +

+  RESOURCE  glucose:initial=10000
+
+

+

+If you wanted to make this into a chemostat with a 10000 equilibrium +concentration for unused resources, you could put: +

+  RESOURCE  maltose:initial=10000:inflow=100:outflow=0.01
+
+

+

+If you want a resource that exists spatially where the resource enters +from the top and flows towards the bottom where it exits the system, +you could use: +

+  RESOURCE lactose:geometry=grid:initial=100000:inflow=100:outflow=0.1:\
+  inflowx1=0:inflowx2=100:inflowy1=0:inflowy2=0:outflowx1=0:outflowx2=100:\
+  outflowy1=100:outflowy2=100:ygravity=0.5
+
+

+

+Defining a resource with no parameters means that it will start at a zero +quantity and have no inflow or outflow. This is sometimes desirable if you +want that resource to only be present as a byproduct of a reaction. +Remember, though, that you should still have an outflow rate if it's in +a chemostat. + + +

+ +

CELL Command

+

+Using Cell can help increase the detail of a spatial resource. Any cell in a +grid can be given their own initial amount of a resource, inflow amount and +outflow rate. These values are in addition to any other values set for the +spatial resource for the entire for the grid (diffusion and gravity for +instance). The command has the format: +

+ 
CELL resource_name:cell_list[:options]
+

+

+Where resource_name is the name of the spatial resource that this +cell command will modify. If this resource has not been defined yet, a new +resource with this name will be created. +

+

+Where cell_list is comma delimited list of cells that will be set. +We treat the grid like a one dimensional array where 0 is the upper left corner, +world_x - 1 is the upper right corner, and (world_x * world_y) - 1 is the +lower right corner. As well as single cell you can also enter a range of +cells by using the format a..b. +

+

+Where options is a colon delimited list of factors that modify the +resource. The following chart specifies these options. +

+
+ +
+

 

+

Table 4: Cell Options

+ + + + + + + + + + + + + + + + + + + + + +
ArgumentDescriptionDefault
inflow + The number of units of the resource that enter a cell at the end of an + update. + 0
outflow + The fraction of the resource that will flow out a cell each update. + 0.0
initial + The initial abundance of the resource in a cell at the start of an + experiment. + 0
+

 

+
+ +

+An example of setting two cells in the glucose spatial resource: +

+ 
CELL glucose:20,50:initial=100:inflow=10:outflow=0.1
+ +

+An example of setting a 3 x 3 square of cells in the middle of a a maltose +spatial resource (assuming a 10 x 10 world): +

+ 
CELL maltose:33..35,43..45,53..55:initial=500:inflow=5:outflow=0.01
+ +

Reactions

+ +

+Reactions are set to allow organisms to consume or produce resources when those +organisms preform certain tasks. Reactions can be used to reward (or punish) +organisms for performing tasks or to set up a "food web". They +are described by the task that triggers them, the processes they +perform (including resources used and the results of using them), and +requisites on when they can occur. +

+ +

REACTION Command

+ 
REACTION  reaction_name  task[:argument:...]  [process:...]  [requisite:...]
+
+

+ Where reaction_name is a unique name for a reaction. +

+

+ Where task is the name of the task that must be be performed to + trigger the reaction. A list of common tasks is listed in Table 3. +

+

+ Where argument is a list of specific arguments needed by the + particular task. +

+ Where process is a colon delimited list of information about how + resources are consumed/produced. Process settings are described in Table 4. +

+

+ Where requisite is a colon delimited list describing when + reactions can be triggered. Requisite settings are described in Table 5. +

+

+Each reaction must have a task that triggers it. Currently, eighty tasks +have been implemented, as summarized in the following table (in approximate +order of complexity): +

+ +
+

 

+

Table 5: Available Tasks

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TaskDescription
echo + This task is triggered when an organism inputs a single number and + outputs it without modification. +
add + This task is triggered when an organism inputs two numbers, sums them + together, and outputs the result. +
sub + This task is triggered when an organism inputs two numbers, subtracts + one from the other, and outputs the result. +
not + This task is triggered when an organism inputs a 32 bit number, + toggles all of the bits, and outputs the result. This is typically + done either by nanding (by use of the nand instruction) the + sequence to itself, or negating it and subtracting one. The latter + approach only works since numbers are stored in twos-complement + notation. +
nand + This task is triggered when two 32 bit numbers are input, the values + are 'nanded' together in a bitwise fashion, and the result is output. + Nand stands for "not and". + The nand operation returns a zero if and only if both inputs are one; + otherwise it returns a one. +
and + This task is triggered when two 32 bit numbers are input, the values + are 'anded' together in a bitwise fashion, and the result is output. + The and operation returns a one if and only if both inputs are one; + otherwise it returns a zero. +
orn + This task is triggered when two 32 bit numbers are input, the values + are 'orn' together in a bitwise fashion, and the result is output. + The orn operation stands for or-not. It is returns true if for each + bit pair one input is one or the other one is zero. +
or + This task is triggered when two 32 bit numbers are input, the values + are 'ored' together in a bitwise fashion, and the result is output. + It returns a one if either the first input or the second input + is a one, otherwise it returns a zero. +
andn + This task is triggered when two 32 bit numbers are input, the values + are 'andn-ed' together in a bitwise fashion, and the result is output. + The andn operation stands for and-not. It only returns a one if + for each bit pair one input is a one and the other input is + not a one. Otherwise it returns a zero. +
nor + This task is triggered when two 32 bit numbers are input, the values + are 'nored' together in a bitwise fashion, and the result is output. + The nor operation stands for not-or and returns a one only if both + inputs are zero. Otherwise a zero is returned. +
xor + This task is triggered when two 32 bit numbers are input, the values + are 'xored' together in a bitwise fashion, and the result is output. + The xor operation stands for "exclusive or" and returns a one + if one, but not both, of the inputs is a one. Otherwise a zero is + returned. +
equ + This task is triggered when two 32 bit numbers are input, the values + are equated together in a bitwise fashion, and the result is output. + The equ operation stands for 'equals' and will return a one if both + bits are identical, and a zero if they are different. +
logic_3AA-
logic_3CP		 + These tasks include all 68 possible unique 3-input logic operations, + many of which don't have easy-to-understand human readable names. +
+

 

+
+ +

+When describing a reaction, the process portion determines consumption +of resources, their byproducts, and the resulting bonuses. There are several +arguments (separated by colons; example below) to detail the use of a resource. +Default values are in brackets: +

+ +
+

 

+

Table 6: Reaction Process Specifications

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ArgumentDescriptionDefault
resource + The name of the resource consumed. By default, no resource is being + consumed, and the 'max' limit is the amount absorbed. + infinite
value + Multiply the value set here by the amount of the resource consumed + to obtain the bonus. (0.5 may be inefficient, while 5.0 is very + efficient.) This allows different reactions to make use of the + same resource at different efficiency levels. + 1.0
type + Determines how to apply the bonus (i.e. the amount of the resource + absorbed times the value of this process) to change the merit of the + organism. +
   add: Directly add the bonus to the current merit. +
   mult: Multiply the current merit by the bonus (warning: if + the bonus is ever less than one, this will be detrimental!) +
   pow: Multiply the current merit by 2bonus. + this is effectively multiplicative, but positive bonuses are + always beneficial, and negative bonuses are harmful. +
   enzyme: Add bonus * resource / (resource + ksubm) to the current merit. + This is gives a Michaelis-Menten enzyme type reward where bonus is the Kcat + and the Km is entered. Does not work with unlimited resources. +
   energy: Add the bonus energy to the organism's energy waiting to be applied buffer. Bonus energy can be applied on completion of a reaction, execution of the sleep/eat instruction, or when the organisms divides. See Energy Model documentation for more information. + 		add
maxThe maximum amount of the resource consumed per occurrence.1.0
min + The minimum amount of resource required. If less than this quantity + is available, the reaction ceases to proceed. + 0.0
fracThe maximum fraction of the available resource that can be consumed.1.0
product + The name of the by-product resource. At the moment, only a single + by-product can be produced at a time. + none
conversionThe conversion rate to by-product resource1.0
inst + The instruction that gets executed when this reaction gets performed. If + you do not want an organism to be able to have the instruction in their + genome, you still must put it in the instruction set file, but set its weight + to zero. The instruction is executed at no cost to the organism. + none
lethalWhether the cell dies after performing the process0
randomWhether any produced resource is placed randomly in the world instead of the focal cell.0
depletable + Whether this resource is consumed by reactions. + 1
phenplastbonus + Specify how to handle phenotypic plasticity at run-time. + This option may significantly slow an Avida experiment. + When requested in many of the settings below (*), task + bonuses will be adjusted by the plasticity + of each organism's genotype. Requisites will still be + honored, making true task completion information ambiguous. +
   default: Do not attempt to use the genotype's task plasticity. +
   *nobonus: Do not give a bonus to non-static tasks. +
   *fracbonus: Scale the bonus by how static the task is. +
   *fullbonus: Always reward a task when it is detected. + 		+ default +
ksubm + Km for an enzyme reaction. + + 0.0 +
+

 

+
+ + +

+If no process is given, a single associated process with all default +settings is assumed. If multiple process statements are given, all are +acted upon when the reaction is triggered. Assuming you were going to set +all of the portions of process to be their default values, this portion of +the reaction statement would appear as: +

+  process:resource=infinite:value=1:type=add:max=1:min=0:frac=1:product=none:conversion=1
+
+

+

+This statement has many redundancies; for example, it would indicate that the +associated reaction should use the infinite resource, making 'frac' and 'min' +settings irrelevant. Likewise, since 'product' is set to none, the +'conversion' rate is never considered. +

+

+The requisite entry limits when this reaction can be triggered. The +following requisites (in any combination) are possible: +

+ + +
+

 

+

Table 7: Reaction Requisite Specifications

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ArgumentDescriptionDefault
reaction + This limits this reaction from being triggered until the other + reaction specified here has been triggered first. With this, the + user can force organisms to perform reactions in a specified order. + none
noreaction + This limits this reaction from being triggered if the reaction + specified here has already been triggered. This allows the user to + make mutually exclusive reactions, and force organisms to "choose" + their own path. + none
min_count + This restriction requires that the task used to trigger this reaction + must be performed a certain number of times before the trigger will + actually occur. This (along with max_count) allows the user to + provide different reactions depending on the number of times an + organism has performed a task. + 0
max_count + + This restriction places a cap on the number of times a task can + be done and still trigger this reaction. It allows the user to + limit the number of times a reaction can be done, as well as + (along with min_count) provide different reactions depending on the + number of times an organism as performed a task. + INT_MAX
min_tot_count + This restriction requires that the total number of tasks performed by + the organism must be at least this high before this reaction will trigger. + This (along with max_tot_count) allows the user to provide different + reactions depending on how many tasks an organism performs. + 0
max_tot_count + This restriction places a cap on the number of tasks an organism can do + and still trigger this reaction. It allows the user to limit the number + of tasks that will be rewarded, as well as (along with min_tot_count) provide + different reactions depending on the number of tasks an organism performs. + INT_MAX
reaction_min_count + This restriction requires that the reaction must be performed a certain number + of times before any rewards are given. The restriction refers to the number of + times the specific reaction has been triggered, regardless of how many times + the referenced task has been performed. The reaction process specs max and min + will restrict reactions and their counts, not tasks. + 0
reaction_max_count + This restriction caps the number of times an organism can perform the reaction, + effectively limiting the number of times a reaction will be rewarded. The + restriction refers to the number of times the specific reaction has been triggered, + regardless of how many times the referenced task has been performed. The reaction + process specs max and min will restrict reactions and their counts, not tasks. + INT_MAX
divide_only + This command decides when a task will be checked, if the value is 0 the task + will only be checked when an organism executes an IO. If the value is 1 the task + will only be checked when the organism divides. If the value is 2 the task will be + checked at both times. + 0
parasite_only + This command only allows parasites to get credit for the reaction, not host organisms. + False
+

 

+
+ +

+No restrictions are present by default. If there are multiple requisite +entries, only *one* of them need be satisfied in order to trigger the +reaction. Note though that a single requisite entry can have as many +portions as needed. +

+ +

Examples

+ +

+We could simulate the pre-environment system (in which no resources were +present and task performance was rewarded with a fixed bonus) with a file +including only lines like: +

+  REACTION AND logic:2a process:type=mult:value=4.0   requisite:max_count=1
+  REACTION EQU logic:2h process:type=mult:value=32.0  requisite:max_count=1
+
+

+ +

+No RESOURCE statements need be included since only the infinite resource is +used (by default, since we don't specify another resource's name) +# To create an environment with two resources that are converted back and +forth as tasks are performed, we might have: +

+  RESOURCE  yummyA:initial=1000
+  RESOURCE  yummyB:initial=1000
+  REACTION  AtoB  gobbleA  process:resource=yummyA:frac=0.001:product=yummyB
+  REACTION  BtoA  gobbleB  process:resource=yummyB:frac=0.001:product=yummyA
+
+

+

+A value of 1.0 per reaction is default. Obviously gobbleA and +gobbleB would have to be tasks described within Avida. +

+ +

+A requisite against the other reaction being performed would prevent a +single organism from garnering both rewards in equal measure. +

+

+As an example, to simulate a chemostat, we might have: +

+  RESOURCE glucose:inflow=100:outflow=0.01
+
+

+

+This would create a resource called "glucose" that has a fixed inflow rate of +10000 units where 20% flows out every update. (Leaving a steady state of +50,000 units if no organism-consumption occurs). +

+ +

+Limitations to this system: +

    +
  • + Only a single resource can be required at a time, and only a single + by-product can be produced. +
    • +
+ +

+The default setup is: +

+  REACTION  NOT  not   process:value=1.0:type=pow  requisite:max_count=1
+  REACTION  NAND nand  process:value=1.0:type=pow  requisite:max_count=1
+  REACTION  AND  and   process:value=2.0:type=pow  requisite:max_count=1
+  REACTION  ORN  orn   process:value=2.0:type=pow  requisite:max_count=1
+  REACTION  OR   or    process:value=3.0:type=pow  requisite:max_count=1
+  REACTION  ANDN andn  process:value=3.0:type=pow  requisite:max_count=1
+  REACTION  NOR  nor   process:value=4.0:type=pow  requisite:max_count=1
+  REACTION  XOR  xor   process:value=4.0:type=pow  requisite:max_count=1
+  REACTION  EQU  equ   process:value=5.0:type=pow  requisite:max_count=1
+
+

+ +

+This creates an environment where the organisms get a bonus for performing +any of nine tasks. Since none of the reactions are associated with a +resource, the infinite resource is assumed, which is non-depeletable. +The max_count of one means they can only get the bonus from each reaction +a single time. +

+ +

+A similar setup that has 9 resources, one corresponding to each of the nine +possible tasks listed above is: +

+  RESOURCE  resNOT:inflow=100:outflow=0.01   resNAND:inflow=100:outflow=0.01
+  RESOURCE  resAND:inflow=100:outflow=0.01   resORN:inflow=100:outflow=0.01
+  RESOURCE  resOR:inflow=100:outflow=0.01    resANDN:inflow=100:outflow=0.01
+  RESOURCE  resNOR:inflow=100:outflow=0.01   resXOR:inflow=100:outflow=0.01
+  RESOURCE  resEQU:inflow=100:outflow=0.01
+  
+  REACTION  NOT  not   process:resource=resNOT:value=1.0:frac=0.0025
+  REACTION  NAND nand  process:resource=resNAND:value=1.0:frac=0.0025
+  REACTION  AND  and   process:resource=resAND:value=2.0:frac=0.0025
+  REACTION  ORN  orn   process:resource=resORN:value=2.0:frac=0.0025
+  REACTION  OR   or    process:resource=resOR:value=4.0:frac=0.0025
+  REACTION  ANDN andn  process:resource=resANDN:value=4.0:frac=0.0025
+  REACTION  NOR  nor   process:resource=resNOR:value=8.0:frac=0.0025
+  REACTION  XOR  xor   process:resource=resXOR:value=8.0:frac=0.0025
+  REACTION  EQU  equ   process:resource=resEQU:value=16.0:frac=0.0025
+
+

+ +

Other Commands

+

SET_ACTIVE Command

+

+Allows user to activate or deactivate a reaction. If this command is not +used all reactions are active. +

+
+  SET_ACTIVE type name new_status(default=true)
+
+
+

+ Where type is the type of command to activate/deactivate. + Currently REACTION is the only choice. +

+

+ Where name is the name of the item to activate/deactivate. +

+

+ Where new_status sets if the item is active (0 or FALSE will + deactivate). +

\ No newline at end of file diff --git a/docs/documentation/Events-file.md b/docs/documentation/Events-file.md new file mode 100644 index 0000000..8a78fc2 --- /dev/null +++ b/docs/documentation/Events-file.md @@ -0,0 +1,28 @@ +The events file controls events that need to occur throughout the course of a run. This includes the output of data files as well as active events that effect the population (such as extinction events or changes to the mutation rate). + + + +File Formats + +This file consists of a list of events that will be triggered either singly or periodically. The format for each line is: + +type timing event arguments + +The type determines what kind of timings the event will be based off of. This can be immediate [i], based on update [u], or based on generation [g]. + +The timing should only be included for non-immediate events. If a single number is given for timing, the event occurs at that update/generation. A second number can be included (separated by a colon ':') to indicate how often the event should be repeated. And if a third number is listed (again, colon seperated) this will be the last time the event can occur on. For example, the type and timing `u 100:100:5000` would indicate that the event that follows first occurs at update 100, and repeats every 100 updates thereafter until update 5000. A type timing of g 10:10 would cause the event to be triggered every 10 generations for the entire run. + +The event is simply the name of the action that should be performed, and the arguments detail exactly how it should work when it is triggered. Each action has its own arguments. See the List of Actions for details about all of the available options. + +Some examples: + +i Inject +Inject an additional start creature immediately. + +u 100:100 PrintAverageData +Print out all average measurements collected every one hundred updates, starting at update 100. + +g 10000:10:20000 PrintData dom_info.dat update,dom_fitness,dom_depth,dom_sequence +Between generations 10,000 and 20,000, append the specified information to the file dom_info.dat every ten generations. Specifically, the first column in the file would be update number, second is the fitness of the dominant genotype, followed by the depth in the phylogentic tree of the dominant genotype, and finally its genome sequence. + +[List of Actions](List-of-actions) diff --git a/docs/documentation/Experiment-and-analysis-guides.md b/docs/documentation/Experiment-and-analysis-guides.md new file mode 100644 index 0000000..33784c0 --- /dev/null +++ b/docs/documentation/Experiment-and-analysis-guides.md @@ -0,0 +1,2 @@ +* [[Example Configs]] +* [[Creating a Flame Graph]] diff --git a/docs/documentation/File-settings.md b/docs/documentation/File-settings.md new file mode 100644 index 0000000..1c68694 --- /dev/null +++ b/docs/documentation/File-settings.md @@ -0,0 +1,13 @@ +

This section relates Avida to other files that it requires.

+ + + + + + + + + + + +
DATA_DIRThe name (or path) of the directory where output files generated by Avida should be placed.
EVENT_FILE
ANALYZE_FILE
ENVIRONMENT_FILE 		These settings indicate the names of all of the other configuration files used in an Avida run. See their documentation for more information about how to use these files.
diff --git a/docs/documentation/General-settings.md b/docs/documentation/General-settings.md new file mode 100644 index 0000000..32e2ba5 --- /dev/null +++ b/docs/documentation/General-settings.md @@ -0,0 +1,18 @@ +

This section covers all of the basic variables that describe the Avida run. You will probably not need to change these settings.

+ + + + + + + + + + + + + + + +
RANDOM_SEED The random number seed initializes the random number generator. You should alter only this seed if you want to perform a collection of replicate runs. Setting the random number seed to zero (or a negative number) will base the seed on the starting time of the run -- effectively a random random number seed. In practice, you want to always be able to re-do an exact run in case you want to get more information about what happened.
POPULATION_CAP The carrying capacity of the population (in number of organisms), removing random organisms when new organisms are born. Use 0 for no cap.
POP_CAP_ELDEST Also applies a population cap, but removes the oldest organisms in the world.
+

Other general settings are described in the avida.cfg file itself: VERBOSITY, SPECULATIVE, and POP_CAP_ELDEST.

diff --git a/docs/documentation/Gradient-resources.mediawiki b/docs/documentation/Gradient-resources.mediawiki new file mode 100644 index 0000000..65a10ca --- /dev/null +++ b/docs/documentation/Gradient-resources.mediawiki @@ -0,0 +1,243 @@ +
+

Gradient Resources

+
+Gradient resource format is: +
  GRADIENT_RESOURCE gradient_resource_name[:options]  {gradient_resource_name ...}
+

Gradient Resources

+Like other resources, gradient resources are defined in the Environment File and all entries on a gradient resource line are names of individual resources. Gradient resources are a type of spatial resource, some of the main difference being that gradient resources can move (standard gradient resources and halo gradient resources) and can affect org movements (hills and barriers). + +Currently moving gradient resources are only supported for bounded grid environments. + +
+ +

GRADIENT_RESOURCE Command

+The syntax for the Gradient Resource command is: +
GRADIENT_RESOURCE gradient_resource_name[:options]  {gradient_resource_name ...}
+

Habitats:

+The habitat a resource represents controls both the specifications of the resource (i.e. moving or stationary, orbiting or bounded within a defined area) and any effect of the resource on the organisms (i.e. blocking or slowing movement). Currently there are 4 habitats implemented: gradient, hills, barriers, and nests. + +

Gradient Resources: Standard and Halo

+Standard gradient and halo resources allows the user to specify resource distributions which change over time. If movement is enabled, the conical resources move around the Avida grid. This movement may be confined to an orbit around a specified anchor cell on the Avida grid (halos) or within a defined bounding box (standard). Gradient resource cones can be capped with a plateau cylinder of a determined height wherever cone height meets or exceeds the value of 1. In terms of actual resource value, this is analogous to slicing the cone at height 1 and then setting the actual resource value (plateau) in the sliced area to some flat value. Organisms can use sense instructions to detect resources on all parts of the cone, but they can only consume the resources where the value is >= min value in the associated reaction or collect instruction. Typically, the min value is set so that only the plateau area of the cone can be consumed. When an organism consumes any part of the cone, the cone can be set to stop moving until a predifined number of updates (=decay) has passed or all consumable resource (all cells with value >= 1) has been consumed. The cone is then refreshed at some random location within the specified boundaries. An odd but useful quirk is that if decay is set to 1, you can have walking wounded resources. + +

Barriers: Random, Vertical, and Horizontal

+Barriers are far simpler than halo and standard gradient resources. Barrier resources are simply meant to represent walls which block movement. Barriers are only implemented to be created randomly within the grid (the first block is set down in a random cell, then the next block set in a connected random, E-W, or N-S cell, and so on). For a vertical or horizontal barrier, the build direction is randomly selected at the start and the build continues in that direction until all the blocks are placed. If the end of the world is reached and there are still blocks to place, we go back to the original cell and build in the opposite direction. For random barriers, a random direction is selected at the start. Then, the direction of the build continues unchanged with a 95% probability, and a new random build direction with 5% probability. The user can also specify and exclusion area by using halo_inner_radius and halo anchors. +Because barriers can be generated in the middle of a run, we allow orgs already standing on a barrier (which should only happen if they are born on a barrier or if a barrier was created underneath them) to continue moving. In other words, they can exit a barrier, but orgs cannot enter one. If an org (not already on a barrier) tries to enter a barrier cell, movement fails and a 0 is returned to the ?BX? register. Orgs can also make use of the sense-faced-habitat instruction to find the most restrictive habitat type in the faced cell. This will return a 1 if the 'worst' resource in the faced cell is a hill, a 2 if a barrier is in the faced cell, and a 0 if no hills or barriers are in the faced cell. + +

Hills

+Hills are simply meant to represent areas which slow movement. Hills are only implemented to be created randomly within the grid. The center block for each occurance of a hill is set down in a random cell, then the rest of the block is drawn in a circle around the center point using a random radius selected from within the config set radius range. The user can also specify and exclusion area by using halo_inner_radius and halo anchors. The effects on movement are determined by the resistance config setting. This is implemented as the probability of successfully moving while on a hill is equal to 1/resistance. As such, on average, an org on a hill with resistance = 4, will have to execute 4 move instructions to move one cell. + +

Nests

+Nests are standard gradient resources, but by declaring a gradient resource to be a nest, the resource will 'hidden' from long-distance sensing instructions such as look-ahead. Dens +Dens are unhidden nests that are visible to instructions like look-ahead. + +

Predatory Resources

+Predatory resources are gradient resources with teeth. See SetPredatoryResource in the events list of actions. + +
+ +  +

Table 1: Gradient Resource Options

+black variables apply to all gradient resource types, +blue variables apply to standard and halo gradient resources +green variables apply only to halo resources +brown(ish) variables apply to halo resources, hills and barriers +red variables apply only to barriers +purple variables apply only to hills +blue-green variables apply to all topographic features (hills, barriers, dens) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ArgumentDescriptionDefault
habitatType of gradient resource. This determines most of the behaviors and effects of the resource.0 = gradient (standard or halo), 1 = hills, 2 = barriers, 3 = nests(hidden), 4 = dens(visible), 5 = predatory, > 5 = other gradient resource (used to differentiate different 'kinds' of food.0
refugeIs the resource a refuge (predation prevented)?0
peakxInitial x-coordinate of cone peak cell. Only affects non-moving peaks. For moving peaks, random coordinates within appropriate bounds will be used.0
peakyInitial y-coordinate of cone peak cell.0
heightHeight in terms of resource value of the cone at the peak center. This affects values along the slope of the cone where the value of any cell on the slope = height/(distance to center + 1). Note that the height of the plateau may supersede the height of the cone, lowering or raising all cell resource values within the plateau to the plateau value. Since slope is height/distance, for a cone having a plateau and a height set to 10, the plateau will be the region of cells 10 or fewer cells from the center.0
plateauStandard and Halo: Actual initial height in terms of resource levels wherever cone height is greater or equal to 1. This will supersede the cone height in eligible cells. A value of -1 turns this option off. Barriers and Hills: Height of the topographic feature. Apart from when plateau = 0 (off) and plateau > 0 (on), the plateau value has no effect outside of providing values for drawing/rendering.-1.0
spreadRadius of the cone in terms of cells (i.e. extent of cone base). Because the spread starts counting the center cell as radius == 0, a spread of 4 will have 9 cells along the E-W/N-S axes (center cell + 4 cells either side). However, the height of this same resource would need to be == 5 to cover the same area with res value >= 1 (since we add 1 to distance from center cell for height).0
decayNumber of updates until gradient resource is refreshed after an organism initially consumes resources in the cone. The refresh will occur even if the plateau has not been completely consumed. If decay = 0, the peak will be regenerated at a new random location every update, regardless of whether any has been consumed. If decay = 1, the cone will never actually be regenerated, but will move continuously. If decay > 1, resources move until some has been consumed. Movement will then halt until decay # updates (including current) have passed and the cone will then be regenerated in a new random location.1
min_xLeftmost coordinate of the rectangle in which resource will move randomly. The resource will stop moving left and bounce in a new random direction (inside the rectangle) when the edge of the plateau hits min_x. The case is the same for max_x, min_y, and max_y.0
max_xRightmost coordinate of the rectangle in which resource will move randomly.0
min_yTopmost coordinate of the rectangle in which resource will move randomly.0
max_yBottommost coordinate of the rectangle in which resource will move randomly0
thresholdThis set how other parts of avida interact with the resource, specifically look instructions (for now). In the look instructions, anything at or above this value will be treated and counted as an 'edible' cell.1.0
move_a_scalerMeasure of resource movement smoothness taken from the variable "A" in equation 1 from Morrison and DeJong's DF-1 Algorithm. Values range from 1 to 4. Values from 1 to around 3 yield smooth movements, while larger values yield chaotic movement. In the current implementation of gradient resources, this value is largely irrelevant, but move_a_scaler = 1 means no movement and the common setting for moving peaks is 3.8.1.0
updatestepStandard and Halo: How many updates to wait until changing gradient resouce movement direction. Resources move in random directions, only changing course if they bounce or when updatestep is reached. Low updatestep numbers result in chaotic peak movements (and peaks tend not to travel very far overall). Barriers and Hills: How many updates to wait until regenerating the topographic features at new locations. Any value less than 1 (or >= the number of updates in the run) will turn off regeneration.1
haloDetermines if this is a halo gradient. Instead of moving in a predetermined box, halo resources move randomly in an orbit around some fixed anchor cell. 1 if true, 0 if false. Halos do not use the bounded box (min_x, max_x, min_y, max_y) variables. Instead, they rely on the radius and width definitions to determine movement bounds. Note that orbit distances are in terms of cells, so orbits are rectangle in Avida. A diagonal line of cells count as the same distance as a straight line of cells.0
halo_inner_radiusHalo: Closest (in number of cells) the inner edge of a plateau of a halo resource can be to the anchor cell. If no plateau is set, then this will just be the closest the center peak cell can be to the anchor, i.e. the minimum orbit. If plateau is set, minimum orbit will be halo_inner_radius + height (since radius of plateau = height). If you want a plateau of size 10 to be centered on the anchor point, you would need to set halo_inner_radius = -10. If you want the same peak to orbit the anchor point with no space between the plateau and the anchor, halo_inner_radius would be set to 10. +Hills: Closest any part of any generated hill can be to the given anchor point. For hill placement, the box defined by the anchor point, inner_radius, and hill radius define an exclusion zone for placement of the hill center point and build of the hill.0
halo_widthHow wide in cells the orbit is. The farthest the outer edge of the plateau can be from the anchor cell is halo_inner_radius + halo_width. If halo_width = 2 * height, halo resouces will travel in a fixed orbit, randomly changing orbit direction every updatestep. If halo_width > 2 * height, halo resources will travel along a random orbit between halo_inner_radius and halo_inner_radius + halo_width, changing EITHER orbit or orbit direction every updatestep.0
halo_anchor_xX-coordinate of the anchor cell. For hills this is simply the center point of any exclusion zone and does not otherwise determine where the hill is drawn.0
halo_anchor_yY-coordinate of the anchor cell.0
move_speedHow 'fast' the gradient moves in the grid. Since gradient resources are built on spatial resources and spatial resources are only checked once per update, move_speed actually determines how far, in number of cells, the cone is moved between updates, not in an update. Thus move_speed > 1 will cause peaks to 'jump' ahead. Move speeds less than 1 will 'pause' resources for the abs(move_speed) number of updates between moves. This can be valuable if organisms, due to combinations of genome length and time slicing, are slow to react to resource moves and cannot otherwise keep up with the resource.1
commonIn determining the cell values within the plateau, do we treat them as a common (= 1) resource, or as individual cells (= 0)? If common = 1, and any plateau cells are depletabled by organisms, at each update we look to see how much of the plateau was consumed, divide that by the number of cells in the plateau, subtract that amount from the plateau value at the beginning of the previous update (before depletion), and set all plateau cells to this new value. Thus, at the updates, the effects of depletion is spread out across all plateau cells. Peak height is then recalculated to reflect the change in this value and the entire cone is redrawn, while preserving the original extent of the plateau. If common = 0 resource depletions affect only individual plateau cells and the peak slopes are not changed.0
initialInitial value for all plateau cells. If set to -1 (default), initial cell values will be set == plateau.-1.0
plateau_inflowInflow rate of resources within the plateau. This amount will be added to each cell in the plateau at each update, regardless of common setting. Maximum value for plateau cells (if set at >= 0) remains original plateau value. If common = 1, the inflow is added to the current peak height and height is reset to the new value. All values in the peak are then recalculated, but keeping the original extent of the plateau. Maximum value for height (for cone shape) remains capped at original height value.0.0
plateau_outflowOutflow rate of resource within the plateau. The quantity of resources = outflow * height will be removed from each cell in the plateau at each update, regardless of common setting. Minimum resulting value for plateau cells is 0. If common = 1, the outflow quantity is subtracted from the current peak height and height is reset to the new value. All values in the peak are then recalculated, but keeping the original extent of the plateau. Minimum resulting value for height (cone shape) is 0.0.0
cone_inflowInflow rate of resources for individual cells in the cone. This amount will be added to each cell in the cone at each update. The value for a cell will never exceed that expected based on cone height and distance from center (that is, this is a refill rate as much as it is an inflow). Will not affect height of the cone (as in plateau_inflow) and will not affect any plateau cells (use plateau_inflow and/or gradient_inflow for that). 0.0
cone_outflowOutflow rate for non-plateau cells 0.0
gradient_inflowInflow rate of resources for individual cells in the cone scaled by distance from peak center. This amount / (this_distance + 1) will be added to each cell in the cone at each update. The value for a cell will never exceed that expected based on cone height and distance from center (that is, this is a refill rate as much as it is an inflow). Will not affect height of the cone (as in plateau_inflow) and will not affect any plateau cells (use plateau_inflow for that). Can be combined with cone_inflow and cone_outflow and / or plateau_inflow and plateau_outflow.
+To 'grow' a cone, set the height to spread + 1, add gradient inflow, set initial to 0, and set plateau to be max desired reachable height. Cells in the cone will 'grow' at different rates, with cell height growth stopping when the cell value reaches the plateau value.		0.0
floorMinimum value for cells within the cone. Cells that would otherwise have lower values (based on distance from center) will be set to this value. Floor does not affect plateau cells. Rather, it is intended to keep values along the spread from dropping below 1 for experiments where cell values along the slopes would affect merit rewards.0.0
countThe number of hills or walls/barriers to generate.1
max_sizeThe maximum wall size in number of blocks(cells) or maximum hill radius. Actual hill and wall sizes will be determined by a random number selected between min and max (inclusive), minus any blocks placed off-world or overlapping with other blocks of the same resource (or self for walls, if config = 0).1
min_sizeThe minimum wall or hill size.1
configThe orientation of the wall. 0 = random (all blocks placed randomly, but neighboring, relative to previous block), 1 = vertical (rand N or S from seed block), 2 = horizontal (rand E or W from seed block), 3 = vertical from seed (peakx, peaky) to S, 4 = horizontal from seed (peakx, peaky) to W.For hills, if config == 1, generate 1 hill at the peakx X peaky coordinates.0
resistanceThis is implemented as a simple way of impacting the speed with which orgs can move through/across a hill. On average, an org on a hill will have to execute a number of move instructions equal to the resistance setting to move one cell.Setting resistance to 0 for a wall allows orgs to pass through it (creating a linear landmark rather than a barrier).1.0
+  + +
+An example of setting a halo gradient of cone height 10 and radius 180. The plateau height is 1, meaning that the actual resource height is 1 at cells where the cone height is at least 1. Movement is smooth and is updated every 200 updates. The anchor cell is at 189, 249, and it moves no closer than 10 cells away from the anchor and no farther than 30. The resource is immediately refreshed after it has been consumed by at least one organism. +
GRADIENT_RESOURCE food1:height=10:spread=180:plateau=1:decay=1:move_a_scaler=3.8:updatestep=200:halo=1:halo_inner_radius=10:
halo_anchor_x=189:halo_anchor_y=249:halo_width=20:move_speed=1
+An example of a gradient which will initialize at 189, 249 and is bounded by a 200x200 cell box. The cone height is 20, but the radius is only 10 cells. The plateau is of height 2, and the resource moves only every 10000 updates. +
GRADIENT_RESOURCE nest1:peakx=189:peaky=249:height=20:spread=19:plateau=2:decay=1:min_x=125:max_x=375:min_y=125:max_y=375:

+move_a_scaler=1:updatestep=10000
+Examples of barrier resources. Both will create 5 randomly placed vertical or horizontal walls, each between 10 and 200 cells long. For each barrier instance, the initial 'seed' block will be placed in a random cell. Then the build direction (N or S for the first, E or W for the second) will be chosen and the next block placed in the corresponding neighboring cell until the (randomly chosen) target size is met or the edge of the world is reached. All walls will be dismantled and new sets generated every 250 updates. +
GRADIENT_RESOURCE vert_walls:habitat=2:plateau=1.5:updatestep=250:count=5:max_size=200:min_size=10:config=1
+
GRADIENT_RESOURCE horiz_walls:habitat=2:plateau=1.5:updatestep=250:count=5:max_size=200:min_size=10:config=2
+An example of a hill resource. This will draw 10 randomly placed hills every 1000 updates, with each individual hill having a radius between 50 and 125 cells. No hills will be drawn/placed within 10 cells of the center of the world (49, 49). When crossing any of these hills, an organism, on average, will have to take two steps for every one cell traversed. +
GRADIENT_RESOURCE hills:habitat=1:plateau=0.2:updatestep=1000:count=10:max_size=125:min_size=50:halo_inner_radius=10:
halo_anchor_x=49:halo_anchor_y=49:resistance=2
+ +
diff --git a/docs/documentation/Hand-written-Logic-Nine-Programs.md b/docs/documentation/Hand-written-Logic-Nine-Programs.md new file mode 100644 index 0000000..552ee4f --- /dev/null +++ b/docs/documentation/Hand-written-Logic-Nine-Programs.md @@ -0,0 +1,170 @@ +These programs were written as supplementary material for The Evolutionary Origin of Complex Features from 2003: http://myxo.css.msu.edu/papers/nature2003/. Here are programs that will trigger the nine default logic tasks with the default instruction set. + + + + + +

+ + The following hand-written programs perform the various one- and + two-input logic operations. These programs appear to be the shortest + ones to perform these operations that do not depend on the initial + content of stacks and registers (whose initial contents are represented + by a '?' below). However, it has not been proven that these are the + shortest programs. None of these programs permit self-replication; + rather, they merely perform a calculation. + + +

+

+ + +
ECHO +
#Inst AX BX CX Stack Output +
1IO ? X ? ? ? +
2IO ? Y ? ? X + +
  +
NOT +
#Inst AX BX CX Stack Output +
1IO ? X ? ? ? +
2push ? X ? X, ?   +
3pop ? X X ?   +
4nop-C   +
5nand ? ~X X ?   +
6IO ? Y X ? ~X + +
  +
NAND +
#Inst AX BX CX Stack Output +
1IO ? X ? ? ? +
2IO ? X Y ? ? +
3nop-C   +
4nand ? X nand Y Y ?   +
5IO ? Z Y ? X nand Y + +
  +
OR_N +
#Inst AX BX CX Stack Output +
1IO ? X ? ? ? +
2IO ? X Y ? ? +
3nop-C   +
4nand ? X nand Y Y ?   +
5nand ? X or ~Y Y ?   +
6IO ? Z Y ? X or ~Y + +
  +
AND +
#Inst AX BX CX Stack Output +
1IO ? X ? ? ? +
2IO ? X Y ? ? +
3nop-C   +
4nand ? X nand Y Y ?   +
5push ? X nand Y Y X nand Y, ?   +
6pop ? X nand Y X nand Y ?   +
7nop-C   +
8nand ? X and Y X nand Y ?   +
9IO ? Z X nand Y ? X and Y + +
  +
OR +
#Inst AX BX CX Stack Output +
1IO ? X ? ? ? +
2push ? X ? X, ?   +
3pop ? X X ?   +
4nop-C   +
5nand ~X X X ?   +
6nop-A   +
7IO ~X Y X ? X +
8push ~X Y X Y, ?   +
9pop ~X Y Y ?   +
10nop-C   +
11nand ~X ~Y Y ?   +
12swap Y ~Y ~X ?   +
13nop-C   +
14nand Y X or Y ~X ?   +
15IO Y Z ~X ? X or Y + +
  +
AND_N +
#Inst AX BX CX Stack Output +
1IO ? X ? ? ? +
2IO ? X Y ? ? +
3nop-C   +
4nand ? X nand Y Y ?   +
5nand ? X or ~Y Y ?   +
6push ~X X or ~Y Y ~X or Y, ?   +
7pop ~X X or ~Y X or ~Y ?   +
8nop-C   +
9nand ? ~X and Y X or ~Y ?   +
10IO ? Z X or ~Y ? ~X and Y + +
  +
NOR +
#Inst AX BX CX Stack Output +
1IO ? X ? ? ? +
2push ? X ? X, ?   +
3pop ? X X ?   +
4nop-C   +
5nand ~X X X ?   +
6nop-A   +
7IO ~X Y X ? X +
8push ~X Y X Y, ?   +
9pop ~X Y Y ?   +
10nop-C   +
11nand ~X ~Y Y ?   +
12swap Y ~Y ~X ?   +
13nop-C   +
14nand Y X or Y ~X ?   +
15push Y X or Y X X or Y, ?   +
16pop Y X or Y X or Y ?   +
17nop-C   +
18nand Y X nor Y X or Y ?   +
19IO Y Z X or Y ? X nor Y + +
  +
XOR +
#Inst AX BX CX Stack Output +
1IO ? X ? ? ? +
2IO ? X Y ? ? +
3nop-C  +
4push ? X Y X, ?   +
5nand ? X nand YY X, ?   +
6swap ? Y X nand YX, ?   +
7nand ? X or ~Y X nand YX, ?   +
8swap X or ~Y ? X nand YX, ?   +
9nop-A  +
10pop X or ~Y X X nand Y?   +
11nand X or ~Y Y or ~X X nand Y?   +
12swap X nand YY or ~X X or ~Y ?   +
13nop-C  +
14nand X nand YX xor Y X or ~Y ?   +
15IO X nand YZ X or ~Y ? X xor Y + + +
  +
EQU +
#Inst AX BX CX Stack Output +
1IO ? X ? ? ? +
2IO ? X Y ? ? +
3nop-C  +
4push ? X Y X, ?   +
5nand ? X nand YY X, ?   +
6swap ? Y X nand YX, ?   +
7nand ? X or ~Y X nand YX, ?   +
8swap X or ~Y ? X nand YX, ?   +
9nop-A  +
10pop X or ~Y X X nand Y?   +
11nand X or ~Y Y or ~X X nand Y?   +
12swap X nand YY or ~X X or ~Y ?   +
13nop-C  +
14nand X nand YX xor Y X or ~Y ?   +
15push X nand YX xor Y X or ~Y X xor Y, ?  +
16pop X nand YX xor Y X xor Y ?   +
17nop-C  +
18nand X nand YX equ Y X xor Y ?   +
19IO X nand YZ X xor Y ? X equ Y + +
+ +
\ No newline at end of file diff --git a/docs/documentation/Home.md b/docs/documentation/Home.md new file mode 100644 index 0000000..510ca8e --- /dev/null +++ b/docs/documentation/Home.md @@ -0,0 +1,29 @@ +Avida is a free, open source software platform for conducting and analyzing experiments with self-replicating and evolving computer programs. It provides detailed control over experimental settings and protocols, a large array of measurement tools, and sophisticated methods to analyze and post-process experimental data. + +The following articles provide a good introduction to Avida: +* [Testing Darwian](http://www.carlzimmer.com/articles/2005.php?subaction=showfull&id=1177184710&archive=&start_from=&ucat=8&) by Carl Zimmer (Cover story of Feb 2005 Discover Magazine). +* [Twice as Natural](http://myxo.css.msu.edu/lenski/pdf/2001,%20Nature,%20Lenski,%20twice%20as%20natural.pdf) by Richard Lenski (2001) +* [Meet the Scientist](http://www.microbeworld.org/index.php?option=com_content&view=article&id=784:mts59-charles-ofria-&catid=37:meet-the-scientist&Itemid=1550) podcast interview of Charles Ofria by Carl Zimmer (2010) + +More detailed materials: +* [About Digital Evolution](wiki/About) +* [Avida: A Software Platform for Research in Computational Evolutionary Biology](http://www.cse.msu.edu/~ofria/pubs/2009AvidaIntro.pdf) by C. Ofria, D.M. Bryson, and C. Wilke (2009). +* The contents of this Wiki + +If you would like to contribute to this documentation, please create an account via the log-in link at the top-right of the page. + +**[New User Information](wiki/New-User-Information)** + +## General Information +* [Beginner Documentation](wiki/Beginner-Documentation) +* [Overview](wiki/Overview) +* [A Guided Tour of the Ancestor and its Hardware](wiki/Default-Ancestor-Guided-Tour) +* [Text Viewer](wiki/Text-Viewer) +* [Configuration and Command Reference](wiki/Configuration-and-Command-Reference) +* [Experiment and Analysis Guides](wiki/Experiment-and-Analysis-Guides) + + +## Developer Resources +* [Developers Guide](wiki/Developers-Guide) +* [Getting Started](wiki/Development-|-Getting-Started) +* [Avida 3 API](wiki/Avida-3-API) \ No newline at end of file diff --git a/docs/documentation/How-to-create-a-deme-replication-event.mediawiki b/docs/documentation/How-to-create-a-deme-replication-event.mediawiki new file mode 100644 index 0000000..daf62e9 --- /dev/null +++ b/docs/documentation/How-to-create-a-deme-replication-event.mediawiki @@ -0,0 +1,33 @@ +

This tutorial will walk you through the steps involved in creating a deme replication event. It assumes that you have basic familiarity with C++ and Avida-ish stuff. There are several different deme replication events. Currently, they include events such as replicate when the deme is full, when the corners are occupied, when a set number of resources has been amassed (the consume-res event). For this tutorial, we'll be using 'consume-res' as an example. To add your new event:Β 

+
    +
  1. Come up with a few definitions for your deme replication trigger. These need to include the name of the trigger (e.g., consume-res), which will be seen externally, and a deme trigger event constant name used for an enumeration (e.g., DEME_TRIGGER_CONSUME_RESOURCES). The enumeration allows you to refer to your trigger by name, rather than an integer.
    2. +
  2. Add your deme trigger event constant name to the enumerated triggers. To do so, go to Definitions.h and search for enum eDEME_TRIGGERS. Add your item right before DEME_TRIGGER_UNKNOWN. For example,Β  +

    Β Β DEME_TRIGGER_CONSUME_RESOURCES, Β  // 10

    +
    3. +
  3. +

    Define your 'trigger' event as part of the Replicate Demes action. To do that, in PopulationActions.cc go to the classΒ cActionReplicateDemes : public Action. Add the name of your trigger and a brief description to the comment:Β 

    +

    'consume-res' ...demes that have consumed a sufficienct amount of resources

    +

    Then, add the same trigger to the end of the list of else if statements Β 

    +

    Β else if (in_trigger == "consume-res") m_rep_trigger = DEME_TRIGGER_CONSUME_RESOURCES

    +
    4. +
  4. +

    Next, add the code that describes when your replication event will occur. In cPopulation.cc, locate the ReplicateDemes function:Β 

    +

    void cPopulation::ReplicateDemes(int rep_trigger, cAvidaContext& ctx)Β 

    +

    Within this function, add your new trigger both to the comments and to the switch statement. For example, for the 'consume-res' event the following line was added to the comment:Β 

    +

    Β 10:'consume-res' ...demes that have consumed a sufficienct amount of resources

    +
    Β And this case statement was added to the switch statement:Β 
    +
    +

    case DEME_TRIGGER_CONSUME_RESOURCES: {

    +

    Β  Β  Β  Β  // check how many resources have been consumed by the deme

    +

    Β  Β  Β  Β  if (source_deme.GetTotalResourceAmountConsumed() <

    +

    Β  Β  Β  Β  Β  Β  m_world->GetConfig().RES_FOR_DEME_REP.Get()) {

    +

    Β  Β  Β  Β  Β  continue;

    +

    Β }

    +

    Note that this code is using information about the deme. Clearly, if your method needs information from the deme and that information doesn't exist, you'll also need to write some code to do that...Β 

    +

     

    +
    +
    5. +
  5. Last, add your new fangled event to the events file (generally events.cfg) and make sure it works.Β  For example: Β  +

    u 1:1:end ReplicateDemes consume-res

    +
    6. +
diff --git a/docs/documentation/Html-output-color-settings.md b/docs/documentation/Html-output-color-settings.md new file mode 100644 index 0000000..f2ed930 --- /dev/null +++ b/docs/documentation/Html-output-color-settings.md @@ -0,0 +1,3 @@ +These set the output colors for data files printed in HTML mode. + +See avida.cfg for these settings: COLOR_DIFF, COLOR_SAME, COLOR_NEG2, COLOR_NEG1, COLOR_POS1, COLOR_POS2, COLOR_MUT_POS, COLOR_MUT_NEUT, COLOR_MUT_NEG, and COLOR_MUT_LETHAL. diff --git a/docs/documentation/Instruction-Set.md b/docs/documentation/Instruction-Set.md new file mode 100644 index 0000000..9cc0ac6 --- /dev/null +++ b/docs/documentation/Instruction-Set.md @@ -0,0 +1,333 @@ +An instruction set is actually a whole set of configurations, usually contained in their own file and included in the avida.cfg file with #include INST_SET=instset.cfg. + +

Specifiying Instruction Sets in avida.cfg

+ +

Instruction sets are actually part of the avida.cfg file. However, instead of writing the instruction set out in avida.cfg itself, which would be rather long and messy, each instruction set is placed in a separate file. A preprocessor include (of the form #include $filename) is then used to include each instruction set in avida.cfg. Multiple instruction sets may be included. +

+

For example, to include the two instruction sets contained in the files instset-heads.cfg and instset-heads-sex.cfg, these lines are placed in avida.cfg: +

+

+#include instset-heads.cfg
+#include instset-heads-sex.cfg +

+

You may optionally name each instruction set as you include it. This allows you to change which file the name refers to when running avida from the command line, using the -def option. The default avida.cfg contains this line:
+#include INST_SET=instset-heads.cfg +

+

This means you may change which file INST_SET refers (for example, change it to instset-heads-sex.cfg) to on the command line like this:
+./avida -def INST_SET instset-heads-sex.cfg
+

+

In this case, INST_SET is simply a variable name with no special meaning. The line might just as easily been #include BOBS_YOUR_UNCLE=instset-heads.cfg

+ + + +

 

+

Specifiying the Instruction Set for an Organism

+ +

Organisms in an avida run may have different instruction sets. Therefore, it is necessary to specify the instruction used by each .org file. At the top of the .org file you must specify the instruction set with the #inst_set keyword, and the hardware type with the hw_type keyword. For example, default-heads.org starts with these two lines: +

+

+#inst_set heads_default
+#hw_type 0 +

+

Note: the name of the instruction set may not be the same as the name of the file containing the instruction set. (Indeed, one file may contain multiple instruction sets.) The name of the instruction set is defined inside its .cfg file by the INSTSET keyword, which also defines the hardware type. + + + +

 

+

The Structure of an Instruction Set File

+ +

An instruction set consists of a name and hardware type, followed by a list of instructions that belong to +that instruction set, each of which may be followed by a series of options that +define how that instruction should be used. The exact format is as follows: +

+

+INSTSET instset-name:hw_type=$hardware_type
+INST inst-name[:options]
+... +

+ +

Multiple instruction sets with unique names may be defined in the same file. All INST statements must follow the +INSTSET statement defining the instruction set.

+ + +

The following options may be specified (as name=value, separated by colons): +

+
redundancy (default = 1)
+
+ 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. CPU costs will pause the + thread that executed the costly instruction, not the whole organism and + only decrement the pause counter each time the paused thread attempts + to run. If multiple threads execute costly instructions, the costs and + pause counts are handled independently (i.e. unique pause count for each thread). +
+
initial_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. +
+
energy_cost
+
+ The number of Energy units required to execute this instruction. Zero is the default if this value is not specified. +
+
addl_time_cost
+
+ The additional cost in terms of phenotype 'age', but not actual instruction cycles. 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. +
+
inst_code +
+ String of 1's and 0's defining the numeric value of a instruction as used by certain operations that 'numberate' + instruction sequences. +
+
res_cost +
+ The cost in units (double) of COLLECT_SPECIFIC_RESOURCE stored in internal bins to execute the instruction. Organisms + that execute an instruction with a res_cost higher than what is internally available will die. Res_cost is not + applied if an instruction fails. In a multi-resource environment, any and all resources can be converted internally + via reactions to a common COLLECT_SPECIFIC_RESOURCE for use with res_cost (COLLECT_SPECIFIC_RESOURCE must still be + declared in environment file, likely with initial=0). Note that the use of res_cost typically needs to be coupled with + RESOURCE_GIVEN_ON_INJECT and RESOURCE_GIVEN_AT_BIRTH in avida.cfg. The default res_cost is 0. +
+
post_cost +
+ CPU cost to be paid AFTER the instruction is executed the first time (e.g. pseudo post-kill handling time in + predators). Post costs are only applied if the instruction executes successfully (differs from regular costs). +
+
bonus_cost +
+ The cost in units (double) of current bonus to successfully execute the instruction. bonus_cost is not + applied if an instruction fails for some other reason. Ultimately this is similar to res_costs when converting a common, + specific resource, but much simpiler. +
+
+ +

 

+

For example, to specify that the nand instruction is both twice as common and twice as expensive as other instructions, you would use this line:

+

INST nand:redundancy=2:cost=2 + + +

 

+

Description of Default Instruction Set

+ +

+Below are the descriptions of the instructions turned on in the file +instset-classic.cfg. 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 than 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](Glossary-- CPU) +component that it affects; see also +nop-register notation and +nop-head notation) or act as part +of a label 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. +If allocation is successful, the original memory size is loaded into the AX register. + + +

(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 label +the follows it, and find the location of a +complement label 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 label. The flow-head +will also be placed at the beginning of the complement label. If no label 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 label that +follows it, and tests if its complement +label 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. diff --git a/docs/documentation/Instset-heads.cfg.md b/docs/documentation/Instset-heads.cfg.md new file mode 100644 index 0000000..e67d90c --- /dev/null +++ b/docs/documentation/Instset-heads.cfg.md @@ -0,0 +1 @@ +The default instruction set file for the Heads architecture. \ No newline at end of file diff --git a/docs/documentation/Internal-resources.md b/docs/documentation/Internal-resources.md new file mode 100644 index 0000000..f37cbfe --- /dev/null +++ b/docs/documentation/Internal-resources.md @@ -0,0 +1,116 @@ +
+

Using Internal Resources

+
+ +

Avida has the ability to allow organisms to uptake resources from the environment and keep them in a private store of "resource bins". These internal resources may then be used instead of the normal environmental resources to complete reactions. + +

Most configuration of internal resource use is done with config options in avida.cfg, all of which are found in the HOARD_RESOURCE_GROUP. Some more advanced uses require modifications to the environment file as well. There is also a family of instructions which allows organisms to manipulate resources. + +

Turning on internal resources

+

Most internal resource code is protected by a guard to make sure it does not slow Avida down if internal resources are not being used. In order to use internal resources, you must change a line in avida.cfg: +

USE_RESOURCE_BINS 0
+to +
USE_RESOURCE_BINS 1
+ +

Basic resource uptake

+
+The collect instruction moves a resource from the environment to the corresponding resource bin in the organism. +
+To remove resource from the environment and transfer it into its private store, an organism must execute the collect instruction (or one like it, see below). This instruction should be added to the instruction set. +
ABSORB_RESOURCE_FRACTION .0025
+This setting controls the fraction of the available environmental resource the organism may absorb. The default value is the same as the default value for the 'frac' reaction specification, so that an organism will remove the same amount of resource from the environment whether it is storing it or using it to complete a reaction. +
MAX_TOTAL_STORED -1
+This setting defines a cap on the maximum total amount of internal resource an organism can store. The default is -1, indicating that there is no cap. + +

nop-specification

+The collect instruction (and most of its variants) determine which resource to affect by looking at the nop instructions which follow it. This specification is robust to both the number of specifying nops (i.e. nop-A, nop-B, and nop-C, but not nop-X) in the instruction set and the number of resources in the environment file. + +

collect always affects a single resource. If there are no nops follwing it, it chooses randomly from all the resources. Increasing levels of specification narrow down the range of the resource spectrum from which it chooses randomly. For example, in a three-nop, nine-resource system, collect nop-A nop-B affects resource 1 (remember resource ids are 0-based), which is usually the resource tied to NOR. + +

+More nops after a collect instruction narrow the range from which the affected resource is chosen. +
+ +

collect variant instructions

+ +

collect-unit-prob

+
+The collect-unit-prob instruction moves 1 unit of a resource to the corresponding internal resource bin. +
+Resources ought to be harder to uptake as they become more scarce. The original collect instruction models this by uptaking a smaller amount of resource as the resource becomes more scarce. collect-unit-prob models the scarcity issue differently: 1 unit of resource is always collected, but the instruction may fail, and fails more frequently as the resource becomes scarce: the instruction has a probability of succeeding equal to the current units of resource available divided by the COLLECT_PROB_DIVISOR setting. This instruction ignores the ABSORB_RESOURCE_FRACTION setting. +
COLLECT_PROB_DIVISOR 1000
+This setting defines the divisor for probabilistic collect instructions, which have a chance of (current level of resource) / COLLECT_PROB_DIVISOR of succeeding -- this chance is capped at 1. As it is a divisor, it should not be set to 0. + +

destroy

+
+The destroy instruction removes a resource from the environment without adding it to the organism's resource bin. +
+The destroy instruction removes an amount of resource from the environment, but does not add it to the organism's internal resource bin. Like collect, the amount removed is governed by ABSORB_RESOURCE_FRACTION. + +

collect-no-env-remove

+
+The collect-no-env-remove instruction adds resource to the internal bins without removing any from the environment. +
+The collect-no-env-remove instruction adds an amount of resource to the internal resource bin of the organism, but does not remove any resource from the environment; it injects extra resource into the system. Even though no resource is removed from the environment, the amount added to the organism is still controlled by the ABSORB_RESOURCE_FRACTION setting. + +

nop-collect

+
+The nop-collect instruction does nothing, but in a nop-specified way. +
+The nop-collect instruction neither adds resource to the organism nor removes it from the environment. Instead, it provides a no-operation instruction to use in comparison with the other collect instructions. It should be used in place of nop-X for such comparisons; since the collect instructions are nop-specified, they effectively "eat" nops, affecting execution flow as well as dealing with resources (see the MAX_LABEL_EXE_SIZE config option). nop-collect affects execution flow in the same way. + +

collect-specific

+
+The collect-specific instruction works like the collect instruction, but is not nop-specified. +
+The collect-specific instruction is not nop-specified (and so should be compared to nop-X rather than nop-collect). Instead, the resource it affects is determined by the config setting COLLECT_SPECIFIC_RESOURCE. +
COLLECT_SPECIFIC_RESOURCE 0
+This setting determines which resource the collect-specific instruction affects. (Remember that resources are numbered from 0 in the order they appear in the environment file.) It also specifies which resource should be added to injected or newborn organisms if non-zero amounts are specified by RESOURCE_GIVEN_ON_INJECT or RESOURCE_GIVEN_AT_BIRTH. It should not be given a value outside of the range of resource ids. + +

collect-specific-ratio

+Rather than collecting a single specific resource, the collect-specific-ratio instruction collects some amount of all resources. By default, it collects one unit of each resource. A different ratio for a given resource can be specified with the config option NON_1_RESOURCE_RATIOS. +
NON_1_RESOURCE_RATIOS resource_index1:amount, resource_index2:amount
+Every time the collect-specific-ratio instruction is executed, the organism executing it collects one of each resource not mentioned in the config setting and the amount specified after the colon for each other resource. (Remember that resources are numbered from 0 in the order they appear in the environment file - resource_index should not be a value outside of the range of resource ids). For instance, a config setting like this: +
NON_1_RESOURCE_RATIOS 1:2, 3:.5
+Would result in the organism collecting 1 unit of resource 0, 2 units of resource 1, .5 units of resource 3, and 1 unit of any additional resources. + +

Using internal resources to complete reactions

+
+An organism will use internal resources to complete reactions when there is more internal resource than available environmental resource. +
+Once an organism has internal resources in its resource bins, it may use internal resources instead of environmental resources to complete reactions. An organism will do this when the amount of environmental resources available is less than the amount of internal resource available. How much of the internal resource is used is controlled with the USE_STORED_FRACTION config setting. The amount of environmental resource which is considered may be controlled by the ENV_FRACTION_THRESHOLD config setting. +
USE_STORED_FRACTION 1.0
+This setting controls the fraction of the internal resource that the organism will use to complete a reaction. By default this 1.0, meaning that the organism will use all the available internal resource to complete a reaction. As a fraction, this value should remain between 0.0 and 1.0. +
ENV_FRACTION_THRESHOLD 1.0
+This setting controls how much of the available environmental resource the organism should consider when deciding which type of resource to use. By default it is set to 1.0, indicating that the organism should consider all the available environmental resource. As a fraction, this value should remain between 0.0 and 1.0 + +

Forcing internal resource use

+
+If environmental resources are invisible to the organism, it will be forced to use only internal resources to complete reactions. +
+It is possible to force organisms to always use internal resources to complete reactions -- consequently forcing the population to either use the collect instruction or become pure self-replicators. This can be done by forcing the organisms to believe that no environmental resource is ever available, setting: +
ENV_FRACTION_THRESHOLD 1.0
+to +
ENV_FRACTION_THRESHOLD 0.0
+As a precaution, you should also change the 'frac' specification of the REACTIONs in your environment file to be 0.0 (rather than the common .0025 or the default 1.0). + +

Resource sources and sinks

+

The most common source of internal resource is via collect or one of its variants, in most cases from the environment (but see collect-no-env-remove). However, an organism may also receive new internal resource when it is injected (if RESOURCE_GIVEN_ON_INJECT is set above 0) or when it is born (if RESOURCE_GIVEN_AT_BIRTH is set above 0). +

RESOURCE_GIVEN_ON_INJECT 0
+This setting specifies the units of the resource given by COLLECT_SPECIFIC_RESOURCE that should be added to an organism when it is injected. The default is to add no resource. +
RESOURCE_GIVEN_AT_BIRTH 0
+This setting specifies the units of the resource given by COLLECT_SPECIFIC_RESOURCE that should be added to an organism when it is born. The default is to add no resource. + +
+When an organism splits, the two daughter cells each recieve half of the internal resources. +
+

When an organism splits into two daughter organisms, each daughter gets half of the original internal resource store if SPLIT_ON_DIVIDE is set. (If it is set to 0, the resource disappears.) +

SPLIT_ON_DIVIDE 1
+This setting determines whether the mother cell's resources should be split between its two daughter cells on division. It defaults to true; if set to 0 (false), the mother cell's internal resource simply disappears. This setting has not been tested with DIVIDE_METHODs other than 1. + +
+When an organism dies, its internal resources are returned to the environment. +
+

When an organism dies, its internal resources are returned to the environment if RETURN_STORED_ON_DEATH is set. +

RETURN_STORED_ON_DEATH
+This setting determines whether an organsim's internal resources are returned to the environment when the organism dies. It defaults to true; if set to 0 (false), the resource simply disappears. This setting has not been tested with deaths not by old age or being overwritten. diff --git a/docs/documentation/Introduction-to-parasites.mediawiki b/docs/documentation/Introduction-to-parasites.mediawiki new file mode 100644 index 0000000..795b185 --- /dev/null +++ b/docs/documentation/Introduction-to-parasites.mediawiki @@ -0,0 +1,48 @@ +

Introduction to Parasites in Avida

+

This introduction assumes some basic knowledge about Avida. In particular, familiarity with the basic organism and hardware as described here will be very useful to have.

+

(Very) Brief Overview of the TransSMT Hardware

+

With that said, parasites currently do not work in the default hardware but rather one that supports better threading capabilities – the TransSMT hardware. The differences aren’t huge, but they deserve their own documentation. Instead, I will just highlight major differences between the hardware types important for parasites, namely memoryspaces and threads.

+

Memory Spaces

+

Memory spaces are regions of memory reserved for genetic instructions such as an individual’s genome. To access these memory spaces, organisms execute the Set-Memory instruction followed by one or more Nop instructions specifying which space to use. In this hardware, the genome copy produced during self-replication must also be in a seperate memory space, as well as any thread processes an individual spawns.

+

Threads

+

Threads in this hardware are distinct code sequences that are executed either in parallel, where all threads execute an instruction per CPU cycle awarded to an individual, or round-robin, where a single instruction from a single thread is exected per awarded CPU cycle and each thread executes in turn. The number of threads an organism is allowed to have, as well as how they are scheduled is controlled by the following config options in the avida.cfg file.

+
    +
  • MAX_CPU_THREADS 1 # Maximum number of Threads a CPU can spawn
    • +
  • THREAD_SLICING_METHOD 0 # 0 = One thread executed per time slice. # 1 = All threads executed each time slice.
    • +
+

Parasites in the TransSMT Hardware

+

Parasites in Avida are almost identical to hosts, self-replicating by copying their genome instruction-by-instruction into a new memory space. However, instead of dividing this new genome off into the world, parasites attempt to infect a random organism in its host’s neighborhood (globaly if BIRTH_METHOD=4 or WORLD_GEOMETRY=7, and honoring the WORLD_GEOMETRY if BIRTH_METHOD is set to any other value) with their offspring parasite genome, becoming a new thread on the host organism. Parasites attempt infection by calling the Inject instruction, which is also Nop-modified to identify the memory space the parasitic thread should occupy.

+

In order for infection to succede, the host must be able to accept a new thread in the memory space the parasite is attempting to occupy. This means the host must have fewer than MAX_CPU_THREADS and that the host has not used the memory space specified by the Inject instruction. More than one parasite per host is not currently supported, thus we typicaly set MAX_CPU_THREADS=2. We can eliminate the effect of host-parasite coevolution via memory space allocation and specification (and as any unforseen side-effects such as parasites overwriting host offspring when specificying a particular memory space) by giving parasites memory spaces entirely seperate from their host’s (PARASITE_MEM_SPACES=1).

+

Parasites as well as hosts can perform logic tasks, and we can use their task-based phenotypes to implement additional mechanisms determining if infection will succeed or not. The config option INFECTION_MECHANISM already has several mechanisms implemented. The implemented options have the following behavior:

+
    +
  • 0 - Infection will succeed independent of task-based phenotypes
    • +
  • 1 - Infection will succeed if the parasite and host have at least one overlapping task (Inverse Gene-for-Gene)
    • +
  • 2 - Infection will succeed if the parasite does at least one task the host does not perform
    • +
  • 3 - Infection will succeed if the parasite and host do the same tasks (Matching Alleles)
    • +
  • 4 - Infection will succeed if the parasite performs all the tasks the host does as well as at least one additional task (Gene-for-Gene)
    • +
+

To have more control over how many CPU cycles a parasite steals from it’s host, PARASITE_VIRULENCE determines the probability that a CPU cycle will be given to the parasite. Thus, when this option is set to 1, the parasite is completely virulent and overtakes all of its host’s CPU cycles. It is also possible to let the parasites evolve their own virulence by setting VIRULENCE_SOURCE=1, and choosing values for both VIRULENCE_MUT_RATE, which controls the probability of mutating a parasites virulence when a new parasite is born, and VIRULENCE_SD, which is the standard deviation of a normal distribution used to determine how much virulence changes when it mutates.

+

 

+

 

+Depiction of a Host-Parasite Interaction +

 

+

 

+

Β Depiction of a Host-Parasite Interaction

+

 

+

Events Typically Used With Parasites

+

InjectParasite is typically called near the beginning of a run to infect a range of cells. It takes a parasite organism file, the memory space label, and the range of cells which should be infected.

+

PrintParasiteTasksData and PrintHostTasksData print the tasks performed by parasites and hosts respectively. Similarly, PrintHostPhenotypeData and PrintParasitePhenotypeData split up the phenotype data, such as the Shannon Diversity and Richness of unique host and parasite phenotypes.

+

Typical Config Settings

+
    +
  • BIRTH_METHOD 4 #Population is well-mixed
    • +
  • INJECT_METHOD 1 #Parasite thread is reset on successful infection
    • +
  • MAX_CPU_THREADS 2 #Only allow one parasite per host
    • +
  • INFECTION_MECHANISM 1 #Parasites infect hosts when they have at least one overlapping task
    • +
  • PARASITE_VIRULENCE 0.8 #Parasites steal 80$ of their host’s CPU cycles
    • +
  • VIRULENCE_SOURCE 0 #Parasites use virulence value from config, instead of evolving it
    • +
  • PARASITE_MEM_SPACES 1 #Parasites get their own memory spaces
    • +
  • PARASITE_NO_COPY_MUT 1 #Parasites don’t use copy mutation rates, so they can have independent mutation rates
    • +
  • REQUIRE_SINGLE_REACTION Β 1 #Require hosts to perform at least one succesful reaction to reproduce
    • +
+

 

+

A set of complete config files and ancestral organisms can be found here.

diff --git a/docs/documentation/List-of-actions.md b/docs/documentation/List-of-actions.md new file mode 100644 index 0000000..24ae0a1 --- /dev/null +++ b/docs/documentation/List-of-actions.md @@ -0,0 +1,1484 @@ +Generated Thu Mar 15 08:45:28 2012 by make_actions_html +
+

List of Actions

+
+ +

Action Categories

+ + +  + + + +There is a large library of actions available for scheduling as events. +Additionally, all of these actions can be used within analyze scripts. +Below you will find a listing of the high level groupings of these +actions, along with detailed sections for each them. + +
Print
Print actions are the primary way of saving data from an Avida experiments.
Population
Population actions modify the state of the population, and will actually change the course of the run.
Environment
Actions that allow user to change properties of the environment, including resources.
Save and Load
Actions that allow for saving and loading large data sets, such as full populations.
Landscape Analysis
Actions that use data from the current state of Avida, process it and then output the results.
Driver
Actions that allow user to control program execution, including experiment termination.
For a brief overview of writing a new action, please see Creating an Action below. + +  +

Alphabetical Listing of Available Actions

+ + + + + + + + +
+AnalyzeLandscape +AnalyzePopulation +AssignRandomCellData +AttackDen +AvidianConjugation +CalcConsensus +ChangeEnvironment +CompeteDemes +CompeteDemes_AttackKillAndEnergyConserve +CompeteDemesByEnergyDistribution +CompeteDemesByNetwork +CompeteDemesByTaskCount +CompeteDemesByTaskCountAndEfficiency +CompeteOrganisms +ConnectCells +CopyDeme +CountMultipleOpinions +CountOpinions +DecayPoints +DelayedDemeEvent +DelayedDemeEventsPerSlots +DeletionLandscape +DemeBalanceTwoTasks +DemeReactionDiversity +DemeResourceThresholdPredicate +Desynchronization +DiffuseHGTGenomeFragments +DisconnectCells +DistributeData +DistributeDataCheaply +DistributeDataEfficiently +DivideDemes +DumpCellDataGrid +DumpClassificationIDGrid +DumpDonorGrid +DumpEnergyGrid +DumpExecutionRatioGrid +DumpFitnessGrid +DumpGenomeLengthGrid +DumpGenotypeColorGrid +DumpGenotypeGrid +DumpHostTaskGrid +DumpIDGrid +DumpLandscape +DumpLastTaskGrid +DumpMaxResGrid +DumpMemory +DumpParasiteGenotypeGrid +DumpParasiteTaskGrid +DumpParasiteVirulenceGrid +DumpPhenotypeIDGrid +DumpReactionGrid +DumpReceiverGrid +DumpSleepGrid +DumpTargetGrid +DumpTaskGrid +DumpVitalityGrid +Echo +Exit +ExitAveGeneration +ExitAveLineageLabelGreater +ExitAveLineageLabelLess +ExitDemeReplications +ExitElapsedTime +Flash +FlushTopNavTrace +FullLandscape +HillClimb +Inject +InjectAll +InjectAllRandomRepro +InjectCanvas +InjectDemes +InjectDemesFromNest +InjectDemesRandom +InjectGroup +InjectModuloDemes +InjectParasite +InjectParasitePair +InjectRandom +InjectRange +InjectResource +InjectScaledResource +InjectSequence +InjectSequenceWDivMutRate +InsertionLandscape +IteratedConsensus +JoinGridCol +JoinGridRow +KillFractionInSequence +KillFractionInSequence_PopLimit +KillInstLimit +KillInstPair +KillMeanBelowThresholdPaintable +KillNBelowResourceThreshold +KillProb +KillRate +KillRectangle +KillWithinRadiusBelowResourceThreshold +KillWithinRadiusBelowResourceThresholdTestAll +KillWithinRadiusMeanBelowResourceThreshold +LoadPopulation +MeasureDemeNetworks +MergeResourceAcrossDemes +MixPopulation +ModMutProb +MutationalNeighborhood +NewTrial +OutflowScaledResource +PairTestLandscape +Pause +PhenotypeMatch +PrecalcLandscape +Pred_DemeEventMoveBetweenTargets +Pred_DemeEventMoveCenter +Pred_DemeEventNUniqueIndividualsMovedIntoTarget +PredictNuLandscape +PredictWLandscape + +PrintAgePolyethismData
+PrintAveNumTasks
+PrintAverageData
+PrintAvgDemeTasksExeData
+PrintAvgTreatableDemeTasksExeData
+PrintAvgUntreatableDemeTasksExeData
+PrintBirthChamber
+PrintBirthChamberMatingTypeHistogram
+PrintCCladeCounts
+PrintCCladeFitnessHistogram
+PrintCCladeRelativeFitnessHistogram
+PrintCellData
+PrintCellVisitsData
+PrintCompetitionData
+PrintConsensusData
+PrintCountData
+PrintCurrentMeanDemeDensity
+PrintCurrentOpinions
+PrintCurrentReactionData
+PrintCurrentReactionRewardData
+PrintCurrentTaskCounts
+PrintData
+PrintDebug
+PrintDemeAllStats
+PrintDemeAverageData
+PrintDemeCompetitionData
+PrintDemeCurrentTaskExeData
+PrintDemeDonorStats
+PrintDemeEnergyDistributionStats
+PrintDemeEnergySharingStats
+PrintDemeFoundersData
+PrintDemeGermlineSequestration
+PrintDemeGlobalResources
+PrintDemeMigrationSuicidePoints
+PrintDemeNetworkData
+PrintDemeNetworkTopology
+PrintDemeOrgReactionData
+PrintDemeOrgTasksData
+PrintDemeOrgTasksExeData
+PrintDemeReactionData
+PrintDemeReactionDiversityReplicationData
+PrintDemeReplicationData
+PrintDemeResourceStats
+PrintDemeResourceThresholdPredicate
+PrintDemeSpacialEnergyStats
+PrintDemeSpacialSleepStats
+PrintDemeStats
+PrintDemesTotalAvgEnergy
+PrintDemeTasksData
+PrintDemeTasksExeData
+PrintDemeTestamentStats
+PrintDemeTreatableCount
+PrintDemeTreatableReplicationData
+PrintDemeUntreatableReplicationData
+PrintDepthHistogram
+PrintDetailedFitnessData
+PrintDetailedSynchronizationData
+PrintDirectReciprocityData
+PrintDivideMutData
+PrintDominantData
+PrintDominantForagerGenotypes
+PrintDominantGenotype
+PrintDominantGroupGenotypes
+PrintDonationStats
+PrintDynamicMaxMinData
+PrintEditDistance
+PrintErrorData
+PrintExtendedTimeData
+PrintFemaleMatePreferenceData
+PrintFlowRateTuples
+PrintGeneticDistanceData
+PrintGenomicSiteEntropy
+PrintGenotypeAbundanceHistogram
+PrintGermlineData
+PrintGroupIds
+PrintGroupsFormedData
+PrintGroupTolerance
+PrintHGTData
+PrintHostDepthHistogram
+PrintHostPhenotypeData
+PrintHostTasksData
+PrintInstructionAbundanceHistogram
+PrintInstructionData
+PrintInternalTasksData
+PrintInternalTasksQualData
+PrintInterruptData
+PrintLineageCounts
+PrintLineageTotals
+PrintLogFitnessHistogram
+PrintMarketData
+PrintMatingDisplayData
+PrintMatingTypeHistogram
+PrintMessageData
+PrintMessageLog
+PrintMigrationData
+PrintMiniTraces
+PrintMicroTraces
+PrintMultiProcessData
+PrintMutationRateData
+PrintNewReactionData
+PrintNewTasksData
+PrintNewTasksDataPlus
+PrintNumOrgsInDeme
+PrintNumOrgsKilledData
+PrintOpinionsSetPerDeme
+PrintOrganismLocation
+PrintParasiteData
+PrintParasiteDepthHistogram
+PrintParasitePhenotypeData
+PrintParasiteTasksData
+PrintPerDemeGenPerFounderData
+PrintPerDemeReactionData
+PrintPerDemeTasksData
+PrintPerDemeTasksExeData
+PrintPhenotypeData
+PrintPhenotypeStatus
+PrintPhenotypicPlasticity
+		 +PrintPlasticGenotypeSummary
+PrintPopulationDistanceData
+PrintPredatorAverageData
+PrintPredatorErrorData
+PrintPredatorInstructionData
+PrintPredatorVarianceData
+PrintMinPreyFailedAttacks
+PrintPredicatedMessages
+PrintPreyAverageData
+PrintPreyErrorData
+PrintPreyInstructionData
+PrintPreyVarianceData
+PrintProfilingData
+PrintReactionData
+PrintReactionExeData
+PrintReactionRewardData
+PrintRelativeFitnessHistogram
+PrintReproData
+PrintReputationData
+PrintResourceData
+PrintSenseData
+PrintSenseExeData
+PrintShadedAltruists
+PrintSimpleConsensusData
+PrintSleepData
+PrintSpeciesAbundanceHistogram
+PrintStatsData
+PrintStringMatchData
+PrintSuccessfulMates
+PrintSynchronizationData
+PrintTargets
+PrintTaskProbHistogram
+PrintTasksData
+PrintTasksExeData
+PrintTaskSnapshot
+PrintTasksQualData
+PrintThreadsData
+PrintTimeData
+PrintToleranceData
+PrintToleranceInstructionData
+PrintTopNavTrace
+PrintTotalsData
+PrintVarianceData
+PrintViableTasksData
+PrintWinningDeme
+RandomLandscape
+RemovePredators
+ReplaceFromGermline
+ReplicateDemes
+ResetDemes
+SampleLandscape
+SaveDemeFounders
+SaveFlameData
+SavePopulation
+SerialTransfer
+SetCellResource
+SetConfig
+SetDemeResource
+SetDemeResourceInflow
+SetDemeResourceOutflow
+SetEnvironmentInputs
+SetEnvironmentRandomMask
+SetFracDemeTreatable
+SetGradientResource
+SetGradientInflow
+SetGradientOutflow
+SetGradientConeInflow
+SetGradientConeOutflow
+SetGradientPlatInflow
+SetGradientPlatOutflow
+SetGradPlatVarInflow
+SetMigrationRate
+SetMutProb
+SetNumInstBefore0Energy
+SetOptimizeMinMax
+SetPeriodicResource
+SetPopCapEnforcement
+SetPredatoryResource
+SetReactionInst
+SetReactionMaxTaskCount
+SetReactionMinTaskCount
+SetReactionTask
+SetReactionValue
+SetReactionValueMult
+SetResource
+SetResourceInflow
+SetResourceOutflow
+SetSeasonalResource
+SetSeasonalResource10Kyears_1To_1
+SetSeasonalResource1Kyears_1To_1
+SetTaskArgDouble
+SetTaskArgInt
+SetTaskArgString
+SetVerbose
+SeverGridCol
+SeverGridRow
+StopFastForward
+SwapCells
+SwapRandomCells
+Synchronization
+TestDominant
+TherapyDecayDemeResource
+TherapyStructuralNumInst
+TherapyStructuralRatioDistBetweenNearest
+ToggleFitnessValley
+ToggleRewardInstruction
+TrackAllMessages
+UnitFitness
+VERBOSE
+ZeroMuts
+ZeroResources
+
+  +

Driver Actions

+These actions control the driver object responsible for executing the current run. +
    +
  • Exit +No ArgumentsUnconditionally terminate the current run.
    • +
  • ExitAveGeneration +<double generation>
    • +
  • ExitAveLineageLabelGreater +<double threshold>Halts the run if the current average lineage label is larger +than threshold.
    • +
  • ExitAveLineageLabelLess +<double threshold>Halts the run if the current average lineage label is smaller +than threshold.
    • +
  • ExitDemeReplications
    • +
  • ExitElapsedTime +<int elapsed time [seconds]>
    • +
  • Pause +No Arguments
    • +
  • StopFastForward +none
    • +
+  +

Environment Actions

+Events that allow user to change environment properties, such as resources +and reaction parameters. +
    +
  • ChangeEnvironment +<string env_string>Action designed to read in and process a line formatted as if it were in the +environment file. This will change +environmental settings on the fly. You should create all resources and +reactions in the environment file and only use this file to change these +resources and reactions. Also, note that this action does not replace reactions already in the environment that share the same name as the argument given to ChangeEnvironment; it simply adds another reaction with the same name.
    • +
  • DelayedDemeEvent +<int x1> <int y1> <int x2> <int y2> <int delay> <int duration> <bool static_position> <int total_events>
    • +
  • DelayedDemeEventsPerSlots +<int x1> <int y1> <int x2> <int y2> <int delay> <int duration> <bool static_position> <int total_slots_per_deme> <int total_events_per_slot_max> <int total_events_per_slot_min> <int tolal_event_flow_levels>
    • +
  • InjectResource +<string res_name> <double res_count>Inject (add) a specified amount of a specified resource. +res_name must already exist as +a resource in environment file.
    • +
  • InjectScaledResource +<string res_name> <double res_count>
    • +
  • MergeResourceAcrossDemes +<string deme_res_name> <string global_res_name>
    • +
  • OutflowScaledResource +<string res_name> <double res_percent>
    • +
  • SetCellResource +<int cell_id> <string res_name> <double res_count>
    • +
  • SetConfig +<string config_var> <string value>
    • +
  • SetDemeResource +<string res_name> <double res_count>
    • +
  • SetDemeResourceInflow +<int deme id> <string resource_name> <double inflow>
    • +
  • SetDemeResourceOutflow +<int deme id> <string resource_name> <double outflow>
    • +
  • SetEnvironmentInputs +<int input_1> <int input_2> <int input_3> Set the inputs that all organisms get from the environment when doing IO to these specific values. There must +be exactly three inputs, and they must have the usual values for the top 8 "key" bits, i.e. they must be of the form +0x0F?????? 0x33?????? 0x55?????? where ? can be replaced with any hexadecimal digit.
    • +
  • SetEnvironmentRandomMask +<int mask>
    • +
  • SetFracDemeTreatable
    • +

  • + SetGradientResource + <string env_string> +

    +

    + Action designed to read in and process a line for ONE gradient resource, + formatted as if it were in the environment file. + This will change environmental settings for this one gradient resource on the fly. + You should create the resource in the environment file and only use this file to + change this resource.
    + Unlike with ChangeEnvironment, no resources other than the one specified in the event + will be affected. +

    +
    • +

  • + SetGradientInflow + <string res_name> <double res_inflow> +

    +

    + Set existing gradient resource plateau inflow rate to a new value, without redrawing + the entire resource. +

    +
    • +

  • + SetGradientOutflow + <string res_name> <double res_outflow> +

    +

    + Set existing gradient resource plateau outflow rate to a new value, without redrawing + the entire resource. +

    +
    • +

  • + SetGradientConeInflow + <string res_name> <double res_inflow> +

    +
    • +

  • + SetGradientConeOutflow + <string res_name> <double res_outflow> +

    +
    • +

  • + SetGradientPlatInflow + <string res_name> <double res_inflow> +

    +
    • +

  • + SetGradientPlatOutflow + <string res_name> <double res_outflow> +

    +
    • +

  • + SetGradPlatVarInflow + <string res_name> <double mean> <double variance> <int type> +

    +

    + Set existing gradient resource plateau inflow rate to a new value, without redrawing + the entire resource, based on a random number pull from normal distribution of this + mean and variance. As such, this uses a half normal or folded normal approach with + expected value = sigma * sqrt(2 /pi). + If type == 0, new inflow will be the random number pulled. + If type > 0, new inflow will be mean + abs(the random number pulled). + If type == 1, new inflow will be max (0, mean - abs(the random number pulled)). + If type == 2, new inflow will be max (0, mean + the random number pulled). +

    +
    • + +
  • SetNumInstBefore0Energy +<int new_value>
    • +
  • SetOptimizeMinMax +No Arguments
    • +
  • SetPeriodicResource +<string reaction_name> <string amplitude> <string pi/frequence> <phaseShift*pi> <string initial_Y>
    • +
  • SetReactionInst +<string reaction_name> <string inst>Set the instruction triggered by this reaction. +reaction_name must already +exist in the environment file. +inst must be in the instruction set.
    • +

  • + SetPopCapEnforcement + [int cap=0] [int rate=1] +

    +

    + Will set POPULATION_CAP to cap and begin killing orgs off at rate rate by killing rate # orgs + 1 every time a new org is born. + Accepts string args (e.g. SetPopCapEnforcement cap=0:rate=1). +

    +
    • +

  • + SetPredatoryResource + <string res_name> <double kill_odds> <double guarded_juvs_per_adult>double detection_prob> +

    +

    + A gradient resource with teeth. If set in motion, will kill with prob kill_odds 1 random org + in each cell of plateau. If it passes over a den resource, will kill unguarded offspring with + probability kill_odds. If an org steps on the resource, the org is killed with probability + kill_odds. detection_prob sets the probability of orgs detecting the predator via look sensors. +

    +
    • + +
  • SetReactionMaxTaskCount +<string reaction_name> <int max_count>Set the max task count required to trigger a reaction to task_count. +reaction_name must already +exist in the environment file.
    • +
  • SetReactionMinTaskCount +<string reaction_name> <int min_count>Set the min task count required to trigger a reaction to task_count. +reaction_name must already +exist in the environment file.
    • +
  • SetReactionTask +<string reaction_name> <string task_name>Set the task required to trigger a reaction to task_name. +reaction_name and task_name must already +exist in the environment file.
    • +
  • SetReactionValue +<string reaction_name> <double value>Set the reaction value to a specific level. +reaction_name must already +exist in the environment file. +value can be negative.
    • +
  • SetReactionValueMult +<string reaction_name> <double value>Multiply the reaction value by the value. +reaction_name must already +exist in the environment file. +value can be negative.
    • +
  • SetResource +<string res_name> <double res_count>Set the resource amount to a specific level. +res_name must already exist as +a resource in environment file.
    • +
  • SetResourceInflow +<string resource_name> <double inflow>Set the resource inflow to a specific level. +res_name must already exist as +a resource in environment file.
    • +
  • SetResourceOutflow +<string resource_name> <double outflow>Set the resource outflow to a specific level. +res_name must already exist as +a resource in environment file.
    • +
  • SetSeasonalResourceSets resource availiblity to seasonal
    • +
  • SetSeasonalResource10Kyears_1To_1Sets resource availiblity to seasonal 1 to -1 for 10K years of 365 updates
    • +
  • SetSeasonalResource1Kyears_1To_1Sets resource availiblity to seasonal 1 to -1 for 1K years of 365 updates
    • +
  • SetTaskArgDouble +<int task> <int arg> <double value>
    • +
  • SetTaskArgInt +<int task> <int arg> <int value>
    • +
  • SetTaskArgString +<int task> <int arg> <string value>
    • +
  • ZeroResources +noneSet all resurce levels to zero.
    • +
+  +

Landscape Analysis Actions

+Landscape analysis actions perform various types mutation studies to +calculate properties of the fitness landscape for a particular genome. +When scheduled as an event during a run, these actions will typically +perform analysis on the dominant genotype. In analyze mode, analysis +is performed on the entire currently selected batch. + +These actions are often very computationally intensive, thus will +take a long time to compute. In order to take advantage of increasingly +available multi-processor/multi-core systems, a number of these actions +have been enhanced to make use of multiple threads to parallize work. +Set the configuration setting MT_CONCURRENCY to the number +of logical processors available to make use of all processor resources +for these compuations. +
    +
  • AnalyzeLandscape +[filename="land-analyze.dat"] [int trials=1000] [int min_found=0] [int max_trials=0] [int max_dist=10]
    • +
  • AnalyzePopulation +[double sample_prob=1] [int landscape=0] [int save_genotype=0] [string filename=""]
    • +
  • DeletionLandscape +[string filename="land-del.dat"] [int distance=1] [string sitecount_file=""]
    • +
  • DumpLandscape +[string filename="land-dump.dat"]
    • +
  • FullLandscape +[string filename="land-full.dat"] [int distance=1] [string entropy_file=""] [string sitecount_file=""]Do a landscape analysis of the dominant genotype or current batch of genotypes, +depending on the current mode. The resulting output is a collection of +statistics obtained from examining all possible mutations at the distance +specified. The default distance is one.
    • +
  • HillClimb +[string filename="hillclimb.dat"]Does a hill climb with the dominant genotype.
    • +
  • InsertionLandscape +[string filename="land-ins.dat"] [int distance=1] [string sitecount_file=""]
    • +
  • MutationalNeighborhood +[string fname="mut-neighborhood.dat"] [int target=-1]
    • +
  • PairTestLandscape +[string filename=""] [int sample_size=0]If sample_size = 0, pairtest the full landscape.
    • +
  • PrecalcLandscape +No ArgumentsPrecalculate the distance 1 full landscape for the current batch in parallel +using multiple threads. The resulting data is stored into the current batch +and can be used by many subsequent output commands within Analyze mode.
    • +
  • PredictNuLandscape +[string filename="land-predict.dat"]
    • +
  • PredictWLandscape +[string filename="land-predict.dat"]
    • +
  • RandomLandscape +[string filename="land-random.dat"] [int distance=1] [int trials=0]
    • +
  • SampleLandscape +[string filename="land-sample.dat"] [int trials=0]
    • +
+  +

Population Actions

+Population events modify the state of the population, and will actually +change the course of the run. There are a wide variety of these. +
    +
  • AssignRandomCellData +[num_cells=deme_size]
    • +

  • + AttackDen + [double probability=0.0] [int juvs_per_adult=1] +

    +

    + Kills each unguarded juv in dens (habitat == 3 or 4) with set probability. juvs_per_adult sets + the ratio of guarding adults to juvs. E.g. if ratio is set to 5 and there are 2 guards and 12 + juveniles in a den, two random juveniles will be attacked with their probability of death at + the set probability. +

    +
    • +
  • AvidianConjugation +(prob. of donation)
    • +
  • CompeteDemes +[int type=1]
    • +
  • CompeteDemes_AttackKillAndEnergyConserve +No Arguments
    • +
  • CompeteDemesByEnergyDistribution +Competes demes according to the distribution of energy among the organisms
    • +
  • CompeteDemesByNetwork +No arguments.
    • +
  • CompeteDemesByTaskCount +Competes demes according to the number of times a given task has been completed within that demeCompetes demes based on the total number of times that a +task has been completed by an organism in the deme since the +was initialized. This action takes one integer parameter representing +number of the task that is to be used for competition. If no parameter +supplied, the class uses the first task defined in the environment file +compete the demes.
    • +
  • CompeteDemesByTaskCountAndEfficiency +Competes demes according to the number of times a given task has been completed within that deme and the efficiency with which it was done
    • +
  • CompeteOrganisms +[int type=0] [int parents_survive=0] [double scaled_time=1.0] [int dynamic_scaling=0]Calculates fitness of each organism in the population and creates a new population of descendants +where each organism has a chance of replication proportional to its fitness. Can be used to make Avida +operate without population dynamics and asynchronous replication, i.e. like a genetic algorithm. If NewTrial +events have occurred since the last CompeteOrganisms event, then the average fitness over those trials +will be used.competition_type controls how the fitnesses of multiple trials determine the overall fitness +used for the competition: 0=geometric mean of fitnesses, 1=scaled geometric mean of fitnesses (the greatest fitness +of each trial is scaled to 1.0 before taking the geometric mean), 2=arithmetic mean, 3=geometric mean plus +rescales effective fitness values by the geometric mean of the difference from the top score and the median.Setting parents_survive to 1, causes the first copy of an organism that makes it into the new +population to be the original (unmutated) parent organism.
    • +
  • ConnectCells +<int cellA_x> <int cellA_y> <int cellB_x> <int cellB_y>Connects a pair of specified cells.
    • +
  • CopyDeme +<int src_id> <int dest_id>
    • +
  • CountMultipleOpinions +[int opinion_count=0]
    • +
  • CountOpinions +[int desired_opinion=0 [int multiplicity=1 [int side=0]]]
    • +
  • DecayPoints +No ArgumentsDecays the number of points a deme has accumulated by +a percentage that is set in the configuration file.
    • +
  • DemeBalanceTwoTasks +Two min and max for not
    • +
  • DemeReactionDiversity +No arguments.
    • +
  • DemeResourceThresholdPredicate +cString resourceName, cString comparisonOperator, double threasholdValue
    • +
  • Desynchronization +No Arguments
    • +
  • DiffuseHGTGenomeFragments +<none>
    • +
  • DisconnectCells +<int cellA_x> <int cellA_y> <int cellB_x> <int cellB_y>Disconnects a pair of specified cells.
    • +
  • DistributeData +No arguments.
    • +
  • DistributeDataCheaply +No arguments.
    • +
  • DistributeDataEfficiently +No arguments.
    • +
  • DivideDemes +No arguments (yet!)
    • +
  • Flash +No arguments
    • +

  • + FlushTopNavTraceNo arguments

    • + Force printing of nav trace (as set up by PrintTopNavTrace) even if all candidate orgs have not been + evaluated / reproduced. +

    + +
  • Inject +[string fname="START_ORGANISM"] [int cell_id=0] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]Inject a single organisms into the population. Arguments must be +included from left to right; if all arguments are left out, the default +creature is the ancestral organism, and it will be injected into cell 0, +have an uninitialized merit, and be marked as liniage id 0.
    • +
  • InjectAll +[string fname="START_ORGANISM"] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]Same as Inject, but no cell_id is specified and the organism is placed +into all cells in the population.
    • +
  • InjectAllRandomRepro +<int length> [double merit=-1] [int lineage_label=0] [double neutral_metric=0]
    • +
  • InjectCanvas +[string fname="START_ORGANISM"] [int canvas_id=0] [int canvas_x=0] [int canvas_y=0] [int group_id=-1] [int forager_type=-1] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]
    • +
  • InjectDemes +[string fname="START_ORGANISM"] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]
    • +
  • InjectDemesFromNest +[int num_orgs=1] [int nest_cellid=0] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]
    • +
  • InjectDemesRandom +[int num_orgs=1] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]
    • +
  • InjectGroup +[string fname="START_ORGANISM"] [int cell_id=0] [int group_id=-1] [int forager_type=-1] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]
    • +
  • InjectModuloDemes +[string fname="START_ORGANISM"] [int mod_num = 1] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]
    • +
  • InjectParasite +<string filename> <string label> [int cell_start=0] [int cell_end=-1]Attempt to inject a parasite genome into the supplied population cell +range with the specified label.
    • +
  • InjectParasitePair +<string filename_genome> <string filename_parasite> <string label> [int cell_start=0] [int cell_end=-1] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]Inject host parasite pairs into the population cell range specified.
    • +
  • InjectRandom +<int length> [int cell_id=0] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]Injects a randomly generated genome of the supplied length into the population.
    • +
  • InjectRange +[string fname="START_ORGANISM"] [int cell_start=0] [int cell_end=-1] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]Injects identical organisms into a range of cells of the population.Example:InjectRange 000-aaaaa.org 0 10Will inject 10 organisms into cells 0 through 9.
    • +
  • InjectSequence +<string sequence> [int cell_start=0] [int cell_end=-1] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]Injects identical organisms based on the supplied genome sequence into +a range of cells of the population.Example:InjectSequence ckdfhgklsahnfsaggdsgajfg 0 10 100Will inject 10 organisms into cells 0 through 9 with a merit of 100.
    • +
  • InjectSequenceWDivMutRate +<string sequence> [int cell_start=0] [int cell_end=-1] [double div_mut_rate=0] [double merit=-1] [int lineage_label=0] [double neutral_metric=0]
    • +
  • IteratedConsensus +[int compete_period=100 [int replace_number=1 [int kill=1 [int restrict_range=1]]]]
    • +
  • JoinGridCol +[int col_id=-1] [int min_row=0] [int max_row=-1]Add connections between cells along a column in an Avida grid.
    • +
  • JoinGridRow +[int row_id=-1] [int min_col=0] [int max_col=-1]Add connections between cells along a row in an Avida grid.
    • +
  • KillFractionInSequence +[double fraction=0.01]
    • +
  • KillFractionInSequence_PopLimit +[double fraction=0.01]
    • +
  • KillInstLimit +[double probability=0.9] [cString inst=nand] [int limit=5]
    • +
  • KillInstPair +[double probability=0.9] [cString inst1=nand] [cString inst2=nor] [int limit=1]
    • +
  • KillMeanBelowThresholdPaintable
    • +
  • KillNBelowResourceThreshold +[int numkills=0, string resource name, double threshold=0]
    • +
  • KillProb +[double probability=0.9]Using the specified probability, test each organism to see if it is killed off.
    • +
  • KillRate +[double probability=0.9]Randomly removes a certain proportion of the population. +In principle, this action does the same thing as the KillProb event. +However, instead of a probability, here one has to specify a rate. The +rate has the same unit as fitness. So if the average fitness is 20000, +than you remove 50% of the population on every update with a removal rate +of 10000.
    • +
  • KillRectangle +[int x1=0] [int y1=0] [int x2=0] [int y2=0]Kill off all organisms in a rectangle defined by the points (x1, y1) and (x2, y2).
    • +
  • KillWithinRadiusBelowResourceThreshold +[int numradii=0, int radius=0, string resource name, double threshold=0, double killdensity=1]
    • +
  • KillWithinRadiusBelowResourceThresholdTestAll +[int numradii=0, int radius=0, string resource name, double threshold=0, double killdensity=1]
    • +
  • KillWithinRadiusMeanBelowResourceThreshold +[int numradii=0, int radius=0, string resource name, double threshold=0, double killdensity=1]
    • +
  • MeasureDemeNetworks +No arguments.
    • +
  • MixPopulation +No arguments.
    • +
  • ModMutProb +[string mut_type="COPY_MUT"] [double prob=0.0] [int start_cell=-1] [int end_cell=-1]Values for mut_type are POINT, COPY_MUT, COPY_INS, COPY_DEL, COPY_UNIFORM, COPY_SLIP, DIV_MUT, DIV_INS, DIV_DEL, DIV_UNIFORM, DIV_SLIP, DIVIDE_MUT, DIVIDE_INS, DIVIDE_DEL, DIVIDE_UNIFORM, DIVIDE_SLIP, PARENT, INJECT_MUT, INJECT_INS, and INJECT_DEL. These correspond to their counterparts in avida.cfg.To turn off all mutations, use ZeroMuts.
    • +
  • NewTrial +No ArgumentsImmediately calculates the fitness of each organism in the population, saves this value for use with the CompeteOrganisms +event, and resets the state of all organisms.
    • +
  • PhenotypeMatch +string file-name
    • +
  • Pred_DemeEventMoveBetweenTargets +[int times=1]
    • +
  • Pred_DemeEventMoveCenter +[int times=1]
    • +
  • Pred_DemeEventNUniqueIndividualsMovedIntoTarget +[int numorgs=1]
    • +

  • + PrintMiniTraces + [boolean random=0] [boolean save_dominants=0] [boolean save_groups=0] [boolean save_foragers=0] [int orgs_per=1] [int max_samples=0] [boolean print_genomes=0] [boolean initial] +

    +

    Prints a condensed trace of execution during a lifetime. Who is traced is determined by arguements. + E.g. with the args save_dominants=1:orgs_per=2, at the specified update(s) a list is + created containing the two most abundant genotypes. The next offspring born to parents with those specified + genotypes will then be traced for their entire lifetimes. If save_foragers is set to 1, the list + would contain the two most abundant genotypes for EACH existing forager type. Multiple types can + be saved without duplicating traces. E.g. save_dominants=1:save_foragers=1:orgs_per=2 would + trace one org from each of the two most dominant genotypes and one org from each of the two most + common genotypes for each of the existing forager types if those genotypes were not also one of the + two most abundant overall. If max_samples is > 0, this will cap the total number of orgs traced with + priorities on fullfilling orgs_per quota for: dominants > forager types > group ids. +

    +

    Setting random will look at current population, select individuals up to max_samples (without replacement) + record the sampled genotypes (one per individual, including genotype duplicates) and then trace the next orgs + born with those genotypes, removing the genotype instance from the 'to-do' list with each new trace. Random option + is not currently compatible with (will override) other save_ arguements or orgs_per. +

    +

    Minitraces are currently only fully implemented for the experimental hardware and partially for + the SMT hardware because of differences in the way some minitrace variables are tracked by the + different hardware types. +

    +

    Each call to PrintMiniTraces resets the genotype list, rather than appending to it. +

    +

    + +

    +
    • + PrintMicroTraces + [boolean random=0] [boolean rand_prey=0] [boolean rand_pred=0] [int next_prey=0] [int next_pred=0] [boolean save_dominants=0] [boolean save_groups=0] [boolean save_foragers=0] [int orgs_per=1] [int max_samples=0] [boolean print_genomes=0] +

    +

    Same general operation behavior as PrintMiniTraces but only saves executed instruction symbols along with + org id, genotype id, forager type, and birth and death updates. Microtraces map executions as 'what the org was trying + to do'. So, failed executions are recorded except when CPU costs are being paid. If CPU costs are being paid, we record + the execution when the instruction was submitted, not necessarily when it was actually executed. Each microtrace is + saved on a single line in microtrace.dat. +

    +

    rand_pred and rand_prey are compatible with each other, building a single list of genotypes to trace based on + current genotypes in the population for each of the two general forager types (will generate a list of 2 X max_samples + if both arguements are used). +

    +

    Each call to PrintMicroTraces appends to the genotype list, rather than replacing it (opposite of mini traces). +

    +

    If next_prey or next_pred are used, the organisms born to parents with prey or predator + foraging targets will be traced, regardless of genotype, until the set arg number have been traced (requested number will + be replaced, not appended to, by subsequent event calls).

    +

    +

    + +
  • RemovePredators
    • +
  • ReplaceFromGermline +[double p(kill)=0.0 [int update_cell_data=0]]
    • +
  • ReplicateDemes +[string trigger=full_deme] +

    Tests all demes in a population and replicates those wherein a specific trigger condition has been met. The available triggers are: +

      +
    • full_deme: All deme cells are occupied by organisms.
      • +
    • corners: The upper-left and lower-right cells in a deme are occupied
      • +
    • deme-age: The deme has reached the age specified as DEMES_MAX_AGE in avida.cfg
      • +
    • birth-count: The deme has reached the number of births specified as DEMES_MAX_BIRTHS in avida.cfg
      • +
    • sat-mov-pred: ???
      • +
    • events-killed: ???
      • +
    • sat-msg-pred: ???
      • +
    • sat-deme-predicate: ???
      • +
    • perf-reactions: ???
      • +
    • consume-res: The deme has consumed a total number of resources specified as RES_FOR_DEME_REP in avida.cfg
      • +
    +

    +
    • +
  • ResetDemes +No Arguments
    • +
  • SerialTransfer +[int transfer_size=1] [int ignore_deads=1]Similar to KillProb, but we specify the exact number of organisms to +keep alive after the event. The ignore_deads +argument determines whether only living organisms are retainted.
    • +
  • SetMigrationRate +[double rate=0.0]
    • +
  • SetMutProb +[string mut_type="COPY_MUT"] [double prob=0.0] [int start_cell=-1] [int end_cell=-1]For a list of values for mut_type, see SetMutProb.
    • +
  • SeverGridCol +[int col_id=-1] [int min_row=0] [int max_row=-1]Remove the connections between cells along a column in an Avida grid.
    • +
  • SeverGridRow +[int row_id=-1] [int min_col=0] [int max_col=-1]Remove the connections between cells along a row in an Avida grid.
    • +
  • SwapCells +<int cell_id1> <int cell_id2> Swaps the two organisms and all associated information (such as previous inputs). Doesn't work with identical cell ids.
    • +
  • SwapRandomCells +<int number swaps> Swaps the specified number of pairs of randomly selected organisms. If randomly selected ids happen to be the same, nothing happens that iteration.
    • +
  • Synchronization +No Arguments
    • +
  • TherapyDecayDemeResource +[string resource_name=resname, string decrease_type=(none|lin|exp), double amount=0.2]
    • +
  • TherapyStructuralNumInst +[cString inst=nand] [double exprWeight=1.0] [double exponent=1.0(linear)]
    • +
  • TherapyStructuralRatioDistBetweenNearest +[cString inst=nand] [double exprWeight=1.0] [double exponent=1.0(linear)] [int print=100]
    • +
  • ToggleFitnessValley +No Arguments
    • +
  • ToggleRewardInstruction +No Arguments
    • +
  • TrackAllMessages +No Arguments
    • +
  • UnitFitness +No arguments.
    • +
  • ZeroMuts +No ArgumentsThis event will set all mutation rates to zero. That is, it will set all cell mutation rates to zero, so that new organisms born will have zero mutation rates. Current organisms will not be affected, and may still mutate.
    • +
+  +

Print Actions

+Output events are the primary way of saving data from an Avida experiments. +The main two types are continuous output, which append to a single file +every time the event is trigged, and singular output, which produce +a single, complete file for each trigger. +
    +
      +
    • CalcConsensus +[int lines_saved=0]
      • +
    • DumpCellDataGrid +[string fname=""]
      • +
    • DumpClassificationIDGrid +[string fname_prefix=""]
      • +
    • DumpDonorGrid +[string fname=""]Print out the grid of organisms who donated their merit.
      • +
    • DumpEnergyGrid +[string fname=""]
      • +
    • DumpExecutionRatioGrid +[string fname=""]
      • +
    • DumpFitnessGrid +[string fname=""]Print out the grid of organism fitness values.
      • +
    • DumpGenomeLengthGrid +[string fname=""]
      • +
    • DumpGenotypeColorGrid +[int num_colors=12] [string fname=""]
      • +
    • DumpGenotypeGrid +[string fname=""]
      • +
    • DumpHostTaskGrid +[string fname=""]Print out the grid of takss that host organisms did in the last gestation cycle. For +each host, tasks are first encoded as a binary string (e.g. 100000001 means that +organism is doing NOT and EQU and then reported as a base-10 number (257 in the example above).
      • +
    • DumpIDGrid +[string fname=""]
      • +
    • DumpLastTaskGrid +[string fname=""]
      • +
    • DumpMaxResGrid +[string fname=""]
      • +
    • DumpMemory +[string fname=""]Dump memory summary information.
      • +
    • DumpParasiteGenotypeGrid +[string fname=""]
      • +
    • DumpParasiteTaskGrid +[string fname=""]Print out the grid of tasks that parasites did last gestation. For each parasite, tasks are first +encoded as a binary string (e.g. 100000001 means that organism is doing NOT and EQU +and then reported as a base-10 number (257 in the example above).
      • +
    • DumpParasiteVirulenceGrid +[string fname=""]
      • +
    • DumpPhenotypeIDGrid +[string fname=""]
      • +
    • DumpReactionGrid +[string fname=""]
      • +
    • DumpReceiverGrid +[string fname=""]
      • +
    • DumpSleepGrid +[string fname=""]
      • +
    • DumpTargetGrid +[string fname=""]
      • +
    • DumpTaskGrid +[string fname=""]Print out the grid of tasks that organisms do. For each organism, tasks are first +encoded as a binary string (e.g. 100000001 means that organism is doing NOT and EQU +and then reported as a base-10 number (257 in the example above).
      • +
    • DumpVitalityGrid +[string fname=""]
      • +
    • Echo +<cString message>Print the supplied message to standard output.
      • +
    • PrintAgePolyethismData +[string fname="age_polyethism.dat"]
      • +
    • PrintAveNumTasks +[string fname=""]
      • +
    • PrintAverageData +[string fname="average.dat"][string filename='average.dat'] +Print all of the population averages the specified file.
      • +
    • PrintAvgDemeTasksExeData +[string fname="avg_deme_tasks_exe.dat"]
      • +
    • PrintAvgTreatableDemeTasksExeData +[string fname="avg_treatable_deme_tasks_exe.dat"]
      • +
    • PrintAvgUntreatableDemeTasksExeData +[string fname="avg_untreatable_deme_tasks_exe.dat"]
      • +
    • PrintBirthChamber +[string fname="birth_chamber/bc-XXXX.dat"] [int hwtype=0]
      • +
    • PrintBirthChamberMatingTypeHistogram +[string fname="birth_chamber_mating_type_histogram.dat"] [int hwtype=0]
      • +
    • PrintCCladeCounts +[filename = "cclade_count.dat"]Print a count of the number of oraganisms belonging to a each coalescence clade currently in the population.This action will only work in run mode.This action will require TRACK_CCLADE to be enabled.
      • +
    • PrintCCladeFitnessHistogram +[filename] [fit_mode] [hist_min] [hist_step] [hist_max]Print a histogram of fitnesses for each coalescence clade in the population.This action will only work in run mode.This action will rerequire TRACK_CCLADE to be enabled.mode may be {CURRENT, ACTUAL, TESTCPU}, whereCURRENT uses the current phenotype value of fitness
      • +
    +
+ACTUALuses the current merit and the true gestation time (via test cpu calculation) +TESTCPUuses the test cpu measurement. +lower_bound, step, upper_bound are log10 values for the individual histogram bins. + +  +
    +
  • PrintCCladeRelativeFitnessHistogram +[filename] [fit_mode] [hist_min] [hist_step] [hist_max]Print a histogram of parent-relative fitness ratios for each coalescence clade in the population.This action will only work in run mode.This action will rerequire TRACK_CCLADE to be enabled.mode may be {CURRENT, ACTUAL, TESTCPU}, whereCURRENT uses the current phenotype value of fitness
    • +
+ACTUALuses the current merit and the true gestation time (via test cpu calculation) +TESTCPUuses the test cpu measurement. +lower_bound, step, upper_bound are values for the individual histogram bins. + +  +
    +
  • PrintCellData +[string fname="cell_data.dat"]
    • +
  • PrintCellVisitsData +[string fname="visits.dat "]
    • +
  • PrintCompetitionData +[string fname="competition.dat"]Print out CompeteOrganism statistics. Make the first call after the first set of trials has been completed to get a complete header.
    • +
  • PrintConsensusData +[string fname="consensus.dat"]
    • +
  • PrintCountData +[string fname="count.dat"]Print all of the statistics the keep track of counts (such as the number of organisms +in the population or the number of instructions executed).
    • +
  • PrintCurrentMeanDemeDensity +[string fname="deme_currentMeanDensity.dat"]
    • +
  • PrintCurrentOpinions +[string fname="opinions.dat"]
    • +
  • PrintCurrentReactionData +[string fname="cur_reactions.dat"]
    • +
  • PrintCurrentReactionRewardData +[string fname="cur_reaction_reward.dat"]
    • +
  • PrintCurrentTaskCounts +[string fname="curr_task_counts.dat"]
    • +
  • PrintData +<cString fname> <cString format>Append to the file specified (continuous output), the data given in the +column list. The column list needs to be a comma-seperated list of +keywords representing the data types. Many possible data types can be +output; see the complete listing for details. +Note that this event will even create a detailed column legend at the top +of your file so you don't need to seperately keep track of what the +columns mean.
    • +
  • PrintDebug +No Arguments
    • +
  • PrintDemeAllStats +No Arguments
    • +
  • PrintDemeAverageData +[string fname="deme_average.dat"]
    • +
  • PrintDemeCompetitionData +[string fname="deme_compete.dat"]
    • +
  • PrintDemeCurrentTaskExeData +[string fname=" deme_cur_task_exe.dat "]
    • +
  • PrintDemeDonorStats +No Arguments
    • +
  • PrintDemeEnergyDistributionStats +No Arguments
    • +
  • PrintDemeEnergySharingStats +No Arguments
    • +
  • PrintDemeFoundersData +[string fname="deme_founders.dat"]
    • +
  • PrintDemeGermlineSequestration +[string fname="deme_germ.dat"]
    • +
  • PrintDemeGlobalResources +No ArgumentsPrints each resource in each deme. The format is different than normal Avida output and no information besides the date and time is given in the comments. +Format at each update: +deme_global_resouces_<update in 6 digits, padded with left 0s> = [ ... +<deme_number> <resource0> etc. +<deme_number> <resource0> etc. +];
    • +
  • PrintDemeMigrationSuicidePoints +[string fname=" deme_mig_suicide_points.dat "]
    • +
  • PrintDemeNetworkData +[string fname="deme_network.dat"]
    • +
  • PrintDemeNetworkTopology +[string fname="deme_network_topology.dat"]
    • +
  • PrintDemeOrgReactionData +[string fname="deme_org_reactions.dat"]
    • +
  • PrintDemeOrgTasksData +[string fname="deme_org_tasks.dat"]
    • +
  • PrintDemeOrgTasksExeData +[string fname="deme_org_tasks_exe.dat"]
    • +
  • PrintDemeReactionData +[string fname="deme_reactions.dat"]
    • +
  • PrintDemeReactionDiversityReplicationData +[string fname="deme_rx_repl.dat"]
    • +
  • PrintDemeReplicationData +[string fname="deme_repl.dat"]
    • +
  • PrintDemeResourceStats +No ArgumentsPrints each resource in each deme, with the format noted in the initial comments as normal.
    • +
  • PrintDemeResourceThresholdPredicate +[string fname="deme_resourceThresholdPredicate.dat"]
    • +
  • PrintDemeSpacialEnergyStats +No Arguments
    • +
  • PrintDemeSpacialSleepStats +No Arguments
    • +
  • PrintDemeStats +No Arguments
    • +
  • PrintDemesTotalAvgEnergy +No Arguments
    • +
  • PrintDemeTasksData +[string fname="deme_tasks.dat"]
    • +
  • PrintDemeTasksExeData +[string fname="deme_tasks_exe.dat"]
    • +
  • PrintDemeTestamentStats +[string fname="deme_testament.dat"]
    • +
  • PrintDemeTreatableCount +[string fname="deme_treatable.dat"]
    • +
  • PrintDemeTreatableReplicationData +[string fname="deme_repl_treatable.dat"]
    • +
  • PrintDemeUntreatableReplicationData +[string fname="deme_repl_untreatable.dat"]
    • +
  • PrintDepthHistogram +[string fname="depth_histogram.dat"]
    • +
  • PrintDetailedFitnessData +[int save_max_f_genotype=0] [int print_fitness_histo=0] [double hist_fmax=1] [double hist_fstep=0.1] [string datafn="fitness.dat"] [string histofn="fitness_histos.dat"] [string histotestfn="fitness_histos_testCPU.dat"]
    • +
  • PrintDetailedSynchronizationData +[string fname="sync-detail.dat"]
    • +
  • PrintDirectReciprocityData +[string fname="reciprocity.dat"]
    • +
  • PrintDivideMutData +[string fname="divide_mut.dat"]Output (regular and log) statistics about individual, per site, rates divide mutation +rates (aver, stdev, skew, cur) to divide_mut.dat. Use with multiple divide instuction set.
    • +
  • PrintDominantData +[string fname="dominant.dat"]Print all of the statistics relating to the dominant genotype.
    • +
  • PrintDominantForagerGenotypes +[string fname=""]
    • +
  • PrintDominantGenotype +[string fname=""]Print the dominant organism's genome (and lots of information about it) +into the file specified. If no filename is given, the genotype's assigned name +is used and the file is placed into the archive subdirectory.
    • +
  • PrintDominantGroupGenotypes +[string fname=""]
    • +
  • PrintDonationStats +No Arguments
    • +
  • PrintDynamicMaxMinData +[string fname=" maxmin.dat "]
    • +
  • PrintEditDistance +[sample size [filename]]
    • +
  • PrintErrorData +[string fname="error.dat"]Print all of the standard errors of the average population statistics.
    • +
  • PrintExtendedTimeData +[string fname="xtime.dat"]
    • +
  • PrintFemaleMatePreferenceData +[string fname="female_mate_preference_data.dat"]
    • +
  • PrintFlowRateTuples +[string fname="flow_rate_tuples.dat"]
    • +
  • PrintGeneticDistanceData +[string ref_creature_file="START_ORGANISM"] [string fname="genetic_distance.dat"]
    • +
  • PrintGenomicSiteEntropy +[filename = "GenomicSiteEntropyData.dat"]This function will take the initial genotype for each organism in the +population/batch, align them, and calculate the per-site entropy of the +aligned sequences. Please note that there may be a variable number +of columns in each line if the runs are not fixed length. The site +entropy will be measured in mers, normalized by the instruction set size. +This is a population/batch measure of entropy, not a mutation-selection balance +measure.
    • +
  • PrintGenotypeAbundanceHistogram +[string fname="genotype_abundance_histogram.dat"]Arguments: [string fname="species_abundance_histogram.dat"]Arguments: [string fname="lineage_totals.dat"] [int verbose=1]Arguments: [string fname="lineage_counts.dat"] [int verbose=1]Writes out a genotype abundance histogram.
    • +
  • PrintGermlineData +[string fname="germline.dat"]
    • +
  • PrintGroupIds +[string fname="groupids.dat"]
    • +
  • PrintGroupsFormedData +[string fname="groupformation.dat"]
    • +
  • PrintGroupTolerance +[string fname="grouptolerance.dat"]
    • +
  • PrintHGTData +[string fname="hgt.dat"]
    • +
  • PrintHostDepthHistogram +[string fname="depth_host_histogram.dat"]
    • +
  • PrintHostPhenotypeData +[string fname="host_phenotype_count.dat"]
    • +
  • PrintHostTasksData +[string fname="host_tasks.dat"]
    • +
  • PrintInstructionAbundanceHistogram +[string fname="instruction_histogram-${inst_set}.dat"] [string inst_set]Appends a line containing the bulk count (abundance) of each instruction +in the population onto a file.
    • +
  • PrintInstructionData +[string fname="instruction-${inst_set}.dat"] [string inst_set]Print the by-organisms counts of what instructions they _successfully_ executed +beteween birth and divide. Prior to their first divide, organisms values for their parents.
    • +
  • PrintInternalTasksData +[string fname="in_tasks.dat"]Print the number of organisms that have performed each task using internal resources.Note that tasks performed using internal resources are also counted as tasks perfomed (by PrintTasksData), so that if you wish to know the number of tasks performed not using internal resources you must do some subtraction.
    • +
  • PrintInternalTasksQualData +[string fname="in_tasks_quality.dat"]Print the total quality of each task when performed using internal resources. (See PrintTasksQualData for more about task quality.
    • +
  • PrintInterruptData +[string fname="interrupt.dat"]
    • +
  • PrintLineageCounts +[string fname="lineage_counts.dat"]\n WARNING: This will only have the appropriate header if all lineages are present before this action is run for the first time.
    • +
  • PrintLineageTotals
    • +
  • PrintLogFitnessHistogram +Parameters: <filename> <mode> <min> <step> <max>Print a histogram of organism fitnesses in the current population.This action will only work in run mode.mode may be {CURRENT, ACTUAL, TESTCPU}, whereCURRENT uses the current phenotype value of fitness
    • +
+ACTUALuses the current merit and the true gestation time (via test cpu calculation) +TESTCPUuses the test cpu measurement. +lower_bound, step, upper_bound are log10 values for the individual histogram bins. + +  +
    +
  • PrintMarketData +[string fname="market.dat"]
    • +
  • PrintMatingDisplayData +[string fname="mating_display_data.dat"]
    • +
  • PrintMatingTypeHistogram +[string fname="mating_type_histogram.dat"]
    • +
  • PrintMessageData +[string fname="message.dat"]
    • +
  • PrintMessageLog +[string fname="message_log.dat"]
    • +
  • PrintMigrationData +[string fname="migration.dat"]
    • +
  • PrintMultiProcessData +[string fname="multiprocess.dat"]
    • +
  • PrintMutationRateData +[string fname="mutation_rates.dat"]Output (regular and log) statistics about individual copy mutation rates +(aver, stdev, skew, cur). Useful only when mutation rate is set per organism.
    • +
  • PrintNewReactionData +[string fname=" newreactions.dat "]Print number of times the particular reaction has newly appeared in the population since +the last time this datum was printed. Newly appeared is defined as an organism triggering +a reaction that was not triggered by its parent.
    • +
  • PrintNewTasksData +[string fname="newtasks.dat "]Print number of times the particular task has newly appeared in the population since +the last time this datum was printed. Newly appeared is defined as an organism executing +a task that was not executed by its parent.
    • +
  • PrintNewTasksDataPlus +[string fname="newtasksplus.dat "]
    • +
  • PrintNumOrgsInDeme +No Arguments
    • +
  • PrintNumOrgsKilledData +[string fname="orgs_killed.dat"]
    • +
  • PrintOpinionsSetPerDeme +[string fname="opinions_set.dat"]
    • +
  • PrintOrganismLocation +[string fname="location.dat"]
    • +
  • PrintParasiteData +[string fname="parasite.dat"]
    • +
  • PrintParasiteDepthHistogram +[string fname="depth_parasite_histogram.dat"]
    • +
  • PrintParasitePhenotypeData +[string fname="parasite_phenotype_count.dat"]
    • +
  • PrintParasiteTasksData +[string fname="parasite_tasks.dat"]
    • +
  • PrintPerDemeGenPerFounderData +[string fname="deme_gen_between_founders.dat"]
    • +
  • PrintPerDemeReactionData +[string fname="per_deme_reactions.dat"]
    • +
  • PrintPerDemeTasksData +[string fname="per_deme_tasks.dat"]
    • +
  • PrintPerDemeTasksExeData +[string fname="per_deme_tasks_exe.dat"]
    • +
  • PrintPhenotypeData +[string fname="phenotype_count.dat"][string filename='phenotype_count.dat'] +Print the number of phenotypes based on tasks executed this update. Executing +a task any number of times is considered the same as executing it once.
    • +
  • PrintPhenotypeStatus +[string fname="phenotype_status.dat"]
    • +
  • PrintPhenotypicPlasticity +[string filename="phenplast"] [int num_trials=1000]This function will provided detailed information about the phenotypic varients +of the current population/batch by running each genome through a test cpu num_trials times. +If this command is executed in run mode, the +filename will be appeneded with -Update.dat where Update +is the current update. In analyze mode, the default file is merely phenplast.dat. +The output file contains the following: id, parent_id, phenotypic_varient_number, frequency, fitness, merit, +gestation_time, and task counts for each phenotypic variant of each genotype.
    • +
  • PrintPlasticGenotypeSummary +[string filename="genotype_plsticity.dat"]
    • +
  • PrintPopulationDistanceData +[string creature="START_ORGANISM"] [string fname=""] [int save_genotypes=0]
    • +
  • PrintPredatorAverageData +[string fname="predator_average.dat"]
    • +
  • PrintPredatorErrorData +[string fname="predator_error.dat"]
    • +
  • PrintMinPreyFailedAttacks +[string fname="failed_attacks.dat"]
    • +
  • PrintPredatorInstructionData +[string fname="predator_instruction-${inst_set}.dat"] [string inst_set]
    • +
  • PrintPredatorVarianceData +[string fname="predator_variance.dat"]
    • +
  • PrintPredicatedMessages +[string fname="messages.dat"]
    • +
  • PrintPreyAverageData +[string fname="prey_average.dat"]
    • +
  • PrintPreyErrorData +[string fname="prey_error.dat"]
    • +
  • PrintPreyInstructionData +[string fname="prey_instruction-${inst_set}.dat"] [string inst_set]
    • +
  • PrintPreyVarianceData +[string fname="prey_variance.dat"]
    • +
  • PrintProfilingData +[string fname="profiling.dat"]
    • +
  • PrintReactionData +[string fname="reactions.dat"]
    • +
  • PrintReactionExeData +[string fname="reactions_exe.dat"]
    • +
  • PrintReactionRewardData +[string fname="reaction_reward.dat"]
    • +
  • PrintRelativeFitnessHistogram +[filename] [fit_mode] [hist_min] [hist_step] [hist_max]Print a histogram of parent-relative fitness ratios for each coalescence clade in the population.This action will only work in run mode.mode may be {CURRENT, ACTUAL, TESTCPU}, whereCURRENT uses the current phenotype value of fitness
    • +
+ACTUALuses the current merit and the true gestation time (via test cpu calculation) +TESTCPUuses the test cpu measurement. +lower_bound, step, upper_bound are values for the individual histogram bins. + +  +
    +
  • PrintReproData +No arguments
    • + Record and print some data up to first reproduction for every org alive now. +
  • PrintReputationData +[string fname="reputation.dat"]
    • +
  • PrintResourceData +[string fname="resource.dat"] [string print_maps="1"]Print the current counts of each resource available to the population. This uses +the environment configuration to determine what resources are in use. Also optionally creates +separate files resource_resource_name.m (in a format that is +designed to be read into Matlab) for each spatial resource. Uses 1 as default but you can put 0 to only print resource.dat and save space.
    • +
  • PrintSenseData +[string fname="sense.dat"]
    • +
  • PrintSenseExeData +[string fname="sense_exe.dat"]
    • +
  • PrintShadedAltruists +[string fname="shadedaltruists.dat"]
    • +
  • PrintSimpleConsensusData +[string fname="simple_consensus.dat"]
    • +
  • PrintSleepData +[string fname="sleep.dat"]
    • +
  • PrintSpeciesAbundanceHistogramWrites out a species abundance histogram.
    • +
  • PrintStatsData +[string fname="stats.dat"]Print all of the miscellanous population statistics.
    • +
  • PrintStringMatchData +[string fname="stringmatch.dat"]
    • +
  • PrintSuccessfulMates +[string fname="mates/mates-XXXX.dat"]
    • +
  • PrintSynchronizationData +[string fname="sync.dat"]
    • +
  • PrintTargets +[string fname="targets.dat"]
    • +
  • PrintTaskProbHistogram +[filename=pp_histogram.dat] [weightbycpus=0]
    • +
  • PrintTasksData +[string fname="tasks.dat"]Print the number of organisms that are able to perform each task. This uses the +environment configuration to determine what tasks are in use.
    • +
  • PrintTasksExeData +[string fname="tasks_exe.dat"]Print number of times the particular task has been executed this update.
    • +
  • PrintTaskSnapshot +[string fname=""]Run all organisms in the population through test cpus and print out the +number of tasks each can perform.
    • +
  • PrintTasksQualData +[string fname="tasks_quality.dat"]Print the total quality of each task. By default a successful task is valued +as 1.0. Some tasks, however, can grant partial values and/or special bonuses +via the quality value.
    • +
  • PrintThreadsData +[string fname="threads.dat"]
    • +
  • PrintTimeData +[string fname="time.dat"]Print all of the timing related statistics.
    • +
  • PrintToleranceData +[string fname="tolerance.dat"]
    • +
  • PrintToleranceInstructionData +[string fname="toleranceinstruction.dat"]
    • + +
  • PrintTopNavTrace +No arguments
    • +

    + Record and print some nav data up to first reproduction for best of orgs alive now, including trace execution, + locations, and facings. Will print these data for the org among those with the highest reaction achieved By + time of reproduction in shortest amount of time (as measured by cycles). Will print nothing if any of the + candidate orgs are still alive when avida exits and no FlushTopNavTrace events were called. +

    + + +
  • PrintTotalsData +[string fname="totals.dat"]Print various totals for the entire length of the run (for example, the total number of +organisms ever).
    • +
  • PrintVarianceData +[string fname="variance.dat"]Print all of the variances of the average population statistics.
    • +
  • PrintViableTasksData +[string fname="viable_tasks.dat"]
    • +
  • PrintWinningDeme +[string fname="deme_winners.dat"]
    • +
  • SaveDemeFounders +[string fname=""]
    • +
  • SetVerbose +[string verbosity=""]Change the level of output verbosity. Verbose messages will print all +of the details of what is happening to the screen. Minimal messages +will only briefly state the process being run. Verbose messages are +recommended if you're in interactive analysis mode. When no arguments +are supplied, action will toggle between NORMAL and ON.Levels: SILENT, NORMAL, ON, DETAILS, DEBUG
    • +
  • TestDominant +[string fname="dom-test.dat"]
    • +
  • VERBOSE +[string verbosity=""]
    • +
+  + +  +

Save Load Actions

+
    +

  • + LoadPopulation + <cString fname> [int update=-1] [int cellid_offset=0] [int lineage_offset=0] [bool load_groups=0] [bool load_birth_cells=0] [bool load_avatars=0] [bool load_rebirth] +

    +

    + Sets up a population based on a save file such as written out by + SavePopulation. It is also possible to append a history file to the + save file, in order to preserve the history of a previous run.
    + update allows user to set the current update number to a new value
    + load_groups allows users to load population files containing individual + group ids (opinions) and forager types (aka saved populations with save_groups = 1)
    + load_birth_cells allows users to drop each org into it's original birth cell. This + can be important for populations in spatial environments where state information + would have been collected as the org moved around the world.
    + e.g to load a population with birth cells and group ids, but without cell, lineage, or update offsets:
    + i LoadPopulation -1 0 0 1 1 0
    + load_rebirth will override load_groups, load_birth_cells, load avatars and inject orgs into their saved birth cells, + put avatars in their birth cells (if avatars are on), assign parent's merit to org (if inherit merit is on) and assign the + parent's forage target if the parent was a 'teacher'
    + i LoadPopulation -1 0 0 0 0 0 1
    +

    +
    • + +
  • SaveFlameData +[string filename="flame"]
    • +
  • SavePopulation +[string filename="detail"] [boolean save_historic=1] [boolean save_groups=0] [boolean save_avatars=0] [boolean save_rebirth=0] Save the genotypes and lots of statistics about the population to the +file specified; if no filename is given, use the name +detail-update.pop. As with clones, the update number +allows a single event to produce many detail files. The details are used +to collect crossection data about the population. +The filename is a string that is used to prefix the update number and file extension, e.g. detail-100.spop. +The save_historic option determines whether the action saves the full history for the current population. + save_groups will append data on current group ids, current forage targets + and the cell orgs were born into for each occurence of each genotype + Using save_rebirth will save additional information about the birth of the organism which + would be required to 'repeat' the birth of the organism as if it was still in the population (for + behavioral trials, etc): + parent_ft, parent is teacher, parent merit (out to 4 dec places) + Using save_rebirth will save all possible columns (i.e. will save all save_groups + all save_avatars data even if + those flags are off). +Save canvas [deprecated] will save information about the canvas location, birth location, and canvas number used by the orgs. If save_canvas is true, save_avatars will be set to false, save_groups will be set to true, and save_rebirth will be set to true. +
    • +
+  +

Creating an Action

+The action source code is contained in the source/action directory. +Each of the individual action categories has its own source code files (e.g. Landcape Actions are located in the LandscapeActions files). + +Each action is derrived from the cAction class. Briefly, to get an action to work you must create a child class that has a Process and GetDescription function defined as well as a constructor. You must also register this new class with the action library. + +So, with that quick review of what must be done, here is a step by step guide to creating an action: +
    +
  1. Identify which of the action categories your action should be assigned to. There are six different action categories described above. Each category has a similar means of creating a new action, but do note that some action commands are generated via macros defined at the top of the files. For instance, in the PrintActions file, you will notice a number of STATS_OUT_FILE macros being used to generate rather repetitively coded standard output files.
    2. +
  2. Create a new class in the file that follows proper naming conventions. Any class should begin with "cAction" and be followed by the name of the action command you will register with the library. For instance, if we were to create a new command "MyAction", we'd name the class cActionMyAction. Below is a stub for this new action class: +
    class cActionMyAction : public cAction
+{
+	private:
+		// Private data members for this action
+	public:
+		cActionMyAction(cWorld* world, const cString& args) : cAction(world, args) { ; }
+
+		static const cString GetDescription() { return "Arguments: My Arguments"; }
+
+		void Process(cAvidaContext& ctx)
+		{
+			//Perform whatever processing is needed when the action is triggered.
+		}
+};
    +
    3. +
  3. Define the private data members, constructor, description string in GetDescription, and the Process function. Any arguments that you specify after the action name in the events configuration will be passed to your new class via the args argument in the constructor. (If you want more documentation for your actions than just the arguments, see the final step in this list.
    4. +
  4. Register the new action with the action library. At the bottom of each action definitions file, there are the commands that register the individual actions with the action library. In the PrintActions.cc file, for instance, this function is called RegisterPrintActions.To register our example action "MyAction", we'd write: +
    action_lib->Register<cActionMyAction>("MyAction");
    + 
    5. +
  5. Test your action.
    6. +
  6. Add a ==== Action action name ==== line in +source/utils/make_actions_html/actions_source_info file
    7. +
\ No newline at end of file diff --git a/docs/documentation/LookSensor.md b/docs/documentation/LookSensor.md new file mode 100644 index 0000000..a59cbb3 --- /dev/null +++ b/docs/documentation/LookSensor.md @@ -0,0 +1,82 @@ +INPUTS READ +Register Functions: + 1st register == habitat type sought + 2nd register == travel/sight distance sought + 3rd register == type of search + 4th register == resource/org id sought + +Habitat + 0 == food + 1 == hills + 2 == walls + 3 == hidden resources (hidden from a distance) + 4 == unhidden dens + -2 == organisms + fail if == 3 (hidden nests) + + -defaults dependent on organisms type + -for pred, default habitat == -2 if invalid habitat input + -for prey, default habitat == 0 if invalid habitat input + +Distance + -default to 1 if low invalid number (aka negative) input + -default to half-log-axis-of-world if high number > half-long-axis + +Search Type + -behavior dependent on habitat used + -if habitat == 0 or 1 or 2 or 4: + 0 = look for closest edible res, closest hill/wall, or closest den (values >=1) + 1 = count # edible cells/walls/hills across entire distance used (values >=1) + -1 = total value of resources of habitat used in cells across entire distance used + + -if habitat == -2: + 0 = closest any org + 1 = closest predator + 2 = count predators + -1 = closest prey + -2 = count prey + + -default to 0 (closest) if invalid input + +ID + -find instances of resource with specified resource or org id + -when searching for a specific organism, search type is ignored + -when searching for a valid specific resource (food/hill/wall/den), the actual habitat type of that resource will be used instead of the input habitat type (if there is a mismatch) + + -default to -1 (no specific target / evaluate all instances of habitat sought) if invalid input + + +  +OUTPUTS WRITTEN +Register Functions: + 1st register == habitat used + 2nd register == travel/sight distance used + 3rd register == search type used + 4th register == resource / org id used + 5th register == count seen + 6th register == values seen + 7th register == id seen + 8th register == org forage target seen + +ITEM NOT SEEN (default register return values): + 1st register == habitat used + 2nd register == -1 + 3rd register == search type used + 4th register == resource / org id used + 5th register == 0 + 6th register == -9 + 7th register == -9 + 8th register == -9 + +ITEM SEEN (overwriting/adding to defaults): + 2nd register == distance used or distance to first object matching search and habitat type + 5th register == count of organism or resource/hill/wall/den cells with value >=1 + -will be 1 if search type specified find nearest + -will be 1 if looking for (and found) specific organism + 6th register == org current bonus for first organism (of correct type) seen + or == summed value of all cells containing resource type searched for + 7th register == group id for first organism (of correct type) seen + or == resource id of first resource of type searched for + 8th register == forage target for first organism (of correct type) seen + + diff --git a/docs/documentation/Mutation-settings.md b/docs/documentation/Mutation-settings.md new file mode 100644 index 0000000..5e6e484 --- /dev/null +++ b/docs/documentation/Mutation-settings.md @@ -0,0 +1,23 @@ +

These settings control how and when mutations occur in organisms. The array of options is dizzying, but only the most commonly used are detailed here. Except that POINT_MUT_PROB isn't actually commonly used.

+ + + + + + + + + + + + + + + + + + + +
POINT_MUT_PROBPoint mutations (sometimes referred to as "cosmic ray" mutations) occur every update; the rate set here is a probability for each site that it will be mutated each update. In other words, this should be a very low value if it is turned on at all. If a mutation occurs, that site is replaced with a random instruction. In practice this also slows Avida down if it is non-zero because it requires so many random numbers to be tested every update.
COPY_MUT_PROBThe copy mutation probability is tested each time an organism copies a single instruction. If a mutation occurs, a random instruction is copied to the destination. In practice this is the most common type of mutations that we use in most of our experiments. The default value is 0.0075, but this is actually higher than you want to use; it is designed to produce pretty results when showing off the viewer. The value we commonly use for our experiments is 0.0025.
DIV_INS_PROB
DIV_DEL_PROB 		These probabilities are tested once per gestation cycle (when an organism is first born) at each position where an instruction could be inserted or deleted, respectively. Each of these mutations change the genome length. Deletions just remove an instruction while insertions add a new, random instruction at the position tested. Multiple insertions and deletions are possible each generation. By default these mutations are turned off.
DIVIDE_MUT_PROB
DIVIDE_INS_PROB
DIVIDE_DEL_PROB 		Divide mutation probabilities are tested when an organism is being divided off from its parent. If one of these mutations occurs, a random site is picked for it within the genome. At most one divide mutation of each type is possible during a single divide. By default, DIVIDE_MUT_PROB is turned off, and both DIVIDE_INS_PROB and DIVIDE_DEL_PROB are set to 0.05, which is a value we often use in our experiments. If you want your organisms never to change in length, obviously, you should turn these insertion and deletion mutations off! (This is not the only thing you need to do; see Fixed-Length Organisms.)
+ +See the avida.cfg file itself for more mutation settings (these are all off by default): COPY_INS_PROB, COPY_DEL_PROB, COPY_UNIFORM_PROB, COPY_SLIP_PROB, DIV_MUT_PROB, DIV_UNIFORM_PROB, DIVIDE_UNIFORM_PROB, DIVIDE_SLIP_PROB, DIVIDE_POISSON_MUT_MEAN, DIVIDE_POISSON_INS_MEAN, DIVIDE_POISSON_DEL_MEAN, DIVIDE_POISSON_SLIP_MEAN, INJECT_INS_PROB, INJECT_DEL_PROB, INJECT_MUT_PROB, SLIP_FILL_MODE, SLIP_COPY_MODE, PARENT_MUT_PROB, SPECIAL_MUT_LINE, META_COPY_MUT, META_STD_DEV, and MUT_RATE_SOURCE. Whew. diff --git a/docs/documentation/Mutations-reversion-settings.md b/docs/documentation/Mutations-reversion-settings.md new file mode 100644 index 0000000..287b3eb --- /dev/null +++ b/docs/documentation/Mutations-reversion-settings.md @@ -0,0 +1,17 @@ +

This section covers tests that are (mostly) very CPU intensive, but allow for Avida experiments that would not be possible in any other system. Basically, each time a mutation occurs, we can run the resulting organism in a test CPU, and determine if that effect of the mutation was lethal, detrimental, neutral, or beneficial. This section allows us to act on this. (Note that as soon as anything here is turned on, the mutations need to be tested. Turning multiple settings on will not cause additional speed decrease)

+ + + + + + + + + + + + + + + +
REVERT_FATAL
REVERT_DETRIMENTAL
REVERT_NEUTRAL
REVERT_BENEFICIAL 		When a mutation occurs of the specified type, the number listed next to that entry is the probability that the mutation will be reverted. That is, the child organism's genome will be restored as if the mutation had never occurred. This allows us both to manually manipulate the abundance of certain mutation types, or to entirely eliminate them.
STERILIZE_FATAL
STERILIZE_DETRIMENTAL
STERILIZE_NEUTRAL
STERILIZE_BENEFICIAL 		The sterilize options work similarly to revert; the difference being that an organism never has its genome restored. Instead, if the selected mutation category occurs, the child is sterilized so that it still takes up space, but can never produce an offspring of its own.
STERILIZE_UNSTABLEIf this toggle is set, organisms must be able to produce exact copies of themselves or else they are sterilized and cannot produce any offspring. An organism that naturally (without any external effects) produces an inexact copy of itself is said to have implicit mutations. If this flag is set, explicit mutations (as described in the mutations section above) can still occur. This particular setting does not seem to be terribly CPU intensive. You must turn this setting on to ensure fixed-length organisms.
diff --git a/docs/documentation/New-user-information.mediawiki b/docs/documentation/New-user-information.mediawiki new file mode 100644 index 0000000..a44d73e --- /dev/null +++ b/docs/documentation/New-user-information.mediawiki @@ -0,0 +1,50 @@ +== Congratulations, you downloaded Avida! DON'T PANIC! == +Next question, how do you run it? + +Like the rest of this wiki, the page is under construction. Please bear with us as we continue to expand this section. + +===Purpose:=== +To help make Avida available to new users without an in-person Β tutorial of what to do and how to do it. + +Avida in its current state runs from the command line on Macs and LinuxΒ distributions. If you don't know how to use the command line here are a couple of tutorials you can use to get familiar: + +Mac users: +* http://osxdaily.com/2007/02/07/basic-command-line-utilities-tips-commands/ +* http://smokingapples.com/software/tutorials/mac-terminal-tips/ + +Linux users: +* http://freeengineer.org/learnUNIXin10minutes.html + +Back to Avida. Assuming you downoaded a stable branch and not a developmentΒ one, using your terminal, locate the directory(folder) you put Avida in. + +'''To run''' just plain Avida type: ./avida +To quit Avida use: ctrl-c +To run Avida with the viewer type (tab-completion, its useful): ./avida-viewer +To quit Avida from the viewer use: q + +If you are using the viewer and want information on all the commands head over toΒ Avida-Viewer. + +===Configuration Files=== + +Now that you have run Avida, lets look at some of the other files included with the program. (Non command line users, the command to look at the files in the directory is: ls ) The following files should be present in the directory: + +* analyze.cfg +* avida.cfg +* environment.cfg +* events.cfg +* instset-heads.cfg +* instset-heads-sex.cfg +* instset-transsmt.cfg +* instset-transsmt.cfg +* default-heads.org +* default-heads-sex.org +* default-transsmt.org + +Lets break that down now. Default Avida runs use: avida.cfg, environment.cfg, events.cfg, instset-heads.cfg and default-heads.org. The other files are for special cases such as sexual reproduction and other things this writer does not understand. + +===avida.cfg:=== + +This file is really really big. Don't let it scare you. Most of it you can ignore to start. There are a few things you might want to look at. Open the file with your favorite (or your UNIX guru's favorite) text editor from the command line (nano, emacs, vi) to be hip or be a square and use a GUI like TextEdit, TextWrangler, or gedit.Β Β Back to things you can change in avida.cfg. There are three sections Topology, Mutation and Reproduction Group. Each section is marked off by ###name###. + +Topology has 3 items of interest to new users: WORLD_X, WORLD_Y & WORLD_GEOMETRY. X & Y control the size of world, and geometry controls how the grid is set up (torodial, bounded, etc). World size inevitably limits the population size while the geometry effects the placement of new offspring. +Mutation has many items of interest to new users. One of the first things to try changing in this section is the mutation rate, per copy. The default is set to 0.0075 mutations per instruction written during replication. This is much higher than most researchers use. Many researchers (that I know) 0.0025 for this setting.Β If you are feeling adventurous you can change the type of mutations ( insertion, deletion, slip etc). Refer to the Mutation Settings for more information/ideas. diff --git a/docs/documentation/Overview.mediawiki b/docs/documentation/Overview.mediawiki new file mode 100644 index 0000000..5078472 --- /dev/null +++ b/docs/documentation/Overview.mediawiki @@ -0,0 +1,5 @@ +Avida is a software platform for experiments with self-replicating and evolving computer programs. It provides detailed control over experimental settings and protocols, a large array of measurement tools, and sophisticated methods to analyze and post-process experimental data. + +In Avida, each digital organism is a self-contained computing automaton that has the ability to construct new automata. The organism is responsible for building the genome (computer program) that will control its offspring automaton and handing that genome to the Avida world. Avida will then construct virtual hardware for the genome to be run on and determine how this new organism should be placed into the population. In a typical Avida experiment, a successful organism attempts to make an identical copy of its own genome, and Avida randomly places that copy into the population, typically by replacing another member of the population. + +In principle, the only assumption made about these self-replicating automata in the core Avida software is that their initial state can be described by a string of symbols (their genome) and that it is possible through processing these symbols to autonomously produce offspring organisms. However, in practice our work has focused on automata with a simple [http://en.wikipedia.org/wiki/Von_Neumann_architecture von Neumann architecture] that operate on an assembly-like language inspired by the Tierra system. Future research projects will likely have us implement additional organism instantiations to allow us to explore additional biological questions. diff --git a/docs/documentation/PrintData-Options.md b/docs/documentation/PrintData-Options.md new file mode 100644 index 0000000..02c3158 --- /dev/null +++ b/docs/documentation/PrintData-Options.md @@ -0,0 +1,59 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeywordDescription
updateCurrent Update
sub_updateInstructions executed within update
generationAverage Generation in Population
entropyGenotype Entropy (Diversity)
species_entropySpecies Entropy (Diversity)
energyAverage Inferiority (Energy)
dom_meritAve Merit of Dominant Genotype
dom_gestAve Gestation Time of Dominant Genotype
dom_fitnessAve Fitness of Dominant Genotype
dom_reproAve Repro-Rate of Dominant Genotype
dom_lengthGenome Length of Dominant Genotype
dom_copy_lengthCopied Length of Dominant Genotype
dom_exe_lengthExecuted Length of Dominant Genotype
dom_idID of Dominant Genotype
dom_nameName of Dominant Genotype
dom_birthsBirth Count of Dominant Genotype
dom_breed_trueBreed-True Count of Dominant Genotype
dom_breed_inBreed-In Count of Dominant Genotype
dom_breed_outBreed-Out Count of Dominant Genotype
dom_num_cpusAbundance of Dominant Genotype
dom_depthTree Depth of Dominant Genotype
dom_sequenceSequence of Dominant Genotype
num_birthsCount of Births in Population
num_deathsCount of Deaths in Population
breed_inCount of Non-Breed-True Births
breed_trueCount of Breed-True Births
bred_trueCount of Organisms that have Bred True
num_cpusCount of Organisms in Population
num_genotypesCount of Genotypes in Population
num_thresholdCount of Threshold Genotypes
num_speciesCount of Species in Population
thresh_speciesCount of Threshold Species
num_lineagesCount of Lineages in Population
num_parasitesCount of Parasites in Population
num_no_birthCount of Childless Organisms
tot_cpusTotal Organisms ever in Population
tot_genotypesTotal Genotypes ever in Population
tot_thresholdTotal Threshold Genotypes Ever
tot_speciesTotal Species ever in Population
tot_lineagesTotal Lineages ever in Population
ave_repro_rateAverage Repro-Rate (1 / Gestation)
ave_meritAverage Merit
ave_ageAverage Age
ave_memoryAverage Memory Used
ave_neutralAverage Neutral Metric
ave_lineageAverage Lineage Label
ave_gestAverage Gestation Time
ave_fitnessAverage Fitness
ave_gen_ageAverage Genotype Age
ave_lengthAverage Genome Length
ave_copy_lengthAverage Copied Length
ave_exe_lengthAverage Executed Length
ave_thresh_ageAverage Threshold Genotype Age
ave_species_ageAverage Species Age
max_fitnessMaximum Fitness in Population
max_meritMaximum Merit in Population
diff --git a/docs/documentation/Quirks.md b/docs/documentation/Quirks.md new file mode 100644 index 0000000..da0504d --- /dev/null +++ b/docs/documentation/Quirks.md @@ -0,0 +1,9 @@ +This page is a list of random trivia that you probably wish you would have known *before* your experiments failed for an obscure reason: + +* Printing genomes during a run changes the outcome of the run. Printing genomes passes orgs through the test cpu. The test cpu process pulls random numbers from the context. Thus, a run cannot be repeated if events calling print genomes are introduced, removed, or otherwise changed. +* The ZeroMutations action does not work on update 0. It gets overridden by the configs. It also does not take effect immediately. Or rather, it immediately sets all mutation rates to zero -- but these can only take effect when the organism actually checks them; in many cases, this is only when an organism divides (see [Mutations Settings](Mutations-Settings). Technically you won't have a 0 mutation rate until all the currently-living organisms have been replaced. +* The default behavior of BIRTH_METHOD=3 (replace empty local cells) is to replace the parent if no cells are empty. Β (Generally, if you wish to allow only empty cells, you must also set ALLOW_PARENT to 0. However, this does not work for BIRTH_METHOD=3 yet.) +* The default behavior for what happens when demes divide (DEMES_DIVIDE_METHOD=0) is for *both* the source and target deme to be replaced. +* Selecting to leave the state of the mother untouched (DIVIDE_METHOD=0) in fact only leaves part of the mother's state untouched. Specifically, it leaves the pointers and register values intact. Almost everything else is reset, though. +* If you have a limited spatial resource with no diffusion that is inflowing on a part of the grid with no organisms (an empty deme for example), it's quantity of resource in the environment doesn't get reported, despite the rate of inflow. (AWC -- 3/29/12) +* When offspring are allocated, their genomes are initialized to be entirely nop-A instructions. As a result, the count of nop-A across all genomes does not actually reflect the frequency with which nop-A is being used, because it includes these placeholder nop-As from offspring that are in the process of being created. \ No newline at end of file diff --git a/docs/documentation/Reproduction-settings.md b/docs/documentation/Reproduction-settings.md new file mode 100644 index 0000000..f3504c6 --- /dev/null +++ b/docs/documentation/Reproduction-settings.md @@ -0,0 +1,28 @@ +These settings control how creatures are born and die in Avida. + + + + + + + + + + + + + + + + + + + + + + + + +
BIRTH_METHODThe birth method sets how the placement of a child organism is determined. Currently, there are six ways of doing this -- the first four (0-3) are all grid-based (offspring are only placed in the immediate neighborhood), and the last two (4-5) assume a well-stirred population. In all non-random methods, empty sites are preferred over replacing a living organism. See the avida.cfg file itself for details.
DEATH_METHOD
AGE_LIMIT 		By default, replacement is the only way for an organism to die in Avida. However, if a death method is set, organisms will die of old age. In method one, organisms will die when they reach the user-specified age limit. In method 2, the age limit is a multiple of their length, so larger organisms can live longer.
ALLOC_METHODDuring the replication process in the default virtual CPU, parent organisms must allocate memory space for their child-to-be. Before the child is copied into this new memory, it must have an initial value. Setting the alloc method to zero sets this memory to a default instruction (typical nop-A). Mode 1 leaves it uninitialized (and hence keeps the contents of the last organism that inhabited that space; if only a partial copy occurs, the child is a hybrid if the parent and the dead organism, hence the name necrophilia). Mode 2 just randomizes each instruction. This means that the organism will behave unpredictably if the uninitialized code is executed.
DIVIDE_METHODWhen a divide occurs, does the parent divide into two children, or else do we have a distinct parent and child? The latter method will allow more age structure in a population where an organism may behave differently when it produces its second or later offspring.
GENERATION_INC_METHODThe generation of an organism is the number of organisms in the chain between it and the original ancestor. Thus, the generation of a population can be calculated as the average generation of the individual organisms. When a divide occurs, the child always receives a generation one higher than the parent, but what should happen to the generation of the parent itself? In general, this should be set the same as divide method.
+ +See the avida.cfg file for further settings: DIVIDE_FAILURE_RESETS, PREFER_EMPTY, ALLOW_PARENT, DISPERSAL_RATE, DEATH_PROB, AGE_LIMIT, AGE_DEVIATION, EPIGENETIC_METHOD, RESET_INPUTS_ON_DIVIDE, INHERIT_MERIT, and INHERIT_MULTITHREAD. diff --git a/docs/documentation/Resource-hoarding-settings.md b/docs/documentation/Resource-hoarding-settings.md new file mode 100644 index 0000000..09abc9e --- /dev/null +++ b/docs/documentation/Resource-hoarding-settings.md @@ -0,0 +1,5 @@ +These settings control internal resources for organisms: how much can be collected at once, limitations on the amount that can be stored, how the internal resources are used to acquire task rewards, and the internal resource state of new organisms. Details are available in the avida.cfg file itself. + +For more information on resource uptake, see Internal Resources: an explanation and guide to use. + +See avida.cfg for these settings: USE_RESOURCE_BINS, ABSORB_RESOURCE_FRACTION, MULTI_ABSORB_TYPE, MAX_TOTAL_STORED, USE_STORED_FRACTION, ENV_FRACTION_THRESHOLD, RETURN_STORED_ON_DEATH, SPLIT_ON_DIVIDE, COLLECT_SPECIFIC_RESOURCE, RESOURCE_GIVEN_ON_INJECT, and RESOURCE_GIVEN_AT_BIRTH. diff --git a/docs/documentation/Sample-analyze-programs.mediawiki b/docs/documentation/Sample-analyze-programs.mediawiki new file mode 100644 index 0000000..e8d4699 --- /dev/null +++ b/docs/documentation/Sample-analyze-programs.mediawiki @@ -0,0 +1,8 @@ +Example analyze programs, with explanations. + +* [[Analyze Mode : Working with Batches|Working With Batches]] +* [[Analyze Mode : Testing a Genome Sequence|Testing a Genome Sequence]] +* [[Analyze Mode : Using Variables|Using Variables]] +* [[Analyze Mode : Finding Lineages|Finding Lineages]] +* [[Analyze Mode : Building Your Own Commands|Building Your Own Commands]] +* [[Analyze Mode : Try It Yourself Exercises|Try It Yourself Exercises]] diff --git a/docs/documentation/Setting-up-fixed-length-organisms.mediawiki b/docs/documentation/Setting-up-fixed-length-organisms.mediawiki new file mode 100644 index 0000000..2330101 --- /dev/null +++ b/docs/documentation/Setting-up-fixed-length-organisms.mediawiki @@ -0,0 +1,21 @@ +In almost all of our experiments, organisms that are all the same length are easier to analyze. We are often willing to be a little less natural to be much more understandable! Here are the avida.cfg settings you will need to change from the default: + + + + + + + + + + +
DIVIDE_INS_PROB and DIVIDE_DEL_PROBInsertion and deletion mutations should be turned off; change these settings to 0.0.
OFFSPRING_SIZE_RANGEOffspring should be exactly the same size as their parents; change this setting to 1.0
+ +Although technically not necessary to keep organisms at a fixed length, there is one more option you probably want to change. One of the main reasons to use fixed length organism is to avoid having to calculate alignments -- you can just line the genomes up. Without the STERILIZE_UNSTABLE option, organisms may have bizarre implicit mutations which break the assumptions of this easy alignment. + + + + + + +
STERILIZE_UNSTABLESometimes organisms have messed-up reproduction cycles that actually causes them to grow or shrink by copying an instruction multiple times or skipping over it entirely. These are not insertion and deletion caused by the process of division, but inherent in the organism's copy loop, so they are not turned off when you turn off DIVIDE_INS_PROB and DIVIDE_DEL_PROB. Avida can, however, check for organisms that are not able to make perfect copies of themselves (i.e. before mutations are imposed) and sterilize them so they do not produce offspring, and this is the setting that turns that checking on. Change it to 1, i.e. "yes".
diff --git a/docs/documentation/Settings-for-genealogy-info-in-the-test-cpu.md b/docs/documentation/Settings-for-genealogy-info-in-the-test-cpu.md new file mode 100644 index 0000000..1df9a6f --- /dev/null +++ b/docs/documentation/Settings-for-genealogy-info-in-the-test-cpu.md @@ -0,0 +1,13 @@ +

These settings control how Avida monitors and deals with genotypes in the Test CPU.

+ + + + + + + + + + + +
THRESHOLDFor some statistics, we only want to measure organisms that we are sure are alive, but its not worth taking the time to run them all in isolation, without outside effect (and in some eco-system situations that isn't even possible!). For these purposes, we call a genotype "threshold" if there have ever been more than a certain number of organisms of that genotype. A higher number here ensures a greater probability that the organisms are indeed "alive".
TEST_CPU_TIME_MODMany of our analysis methods require that we be able to run organisms in isolation. Unfortunately, some of these organisms we test might be non-viable. At some point, we have to give up the test and label it as non-viable, but we can't give up too soon or else we might miss a viable, though slow, replicator. This setting is multiplied by the length of the organism's genome in order to determine how many CPU-cycles to run the organism for. A setting of 20 effectively means that the average instruction must be executed twenty times before we give up. In practice, most organisms have an efficiency here of about 5, so 20 works well, but for accurate tests on some pathological organisms, we will be required to raise this number.
diff --git a/docs/documentation/Text-Viewer.mediawiki b/docs/documentation/Text-Viewer.mediawiki new file mode 100644 index 0000000..6cdfc4d --- /dev/null +++ b/docs/documentation/Text-Viewer.mediawiki @@ -0,0 +1,133 @@ +

The viewer has a number of one character commands that can be typed while the program is running. Often the most common commands are shown on the screen between square brackets (for example [Q]). A list of the most common commands:

+
    +
  • Q-- Quit the program
    • +
  • M-- Switch to the map screen which shows a map of the population's fitness, merit, etc.
    • +
  • S-- Switch to the statistics screen which shows information about the population and the dominate organism
    • +
  • A-- Switch to the analyze screen
    • +
  • Z-- Switch to the zoom screen which shows detail about one organism
    • +
  • H-- Switch to the histogram screen which shows the abundance of genotypes/species in the population
    • +
  • E-- Switch to the environment screen which shows the resources and reactions in the world
    • +
  • O-- Switch to the options screen which shows current settings
    • +
  • B-- Blank the screen
    • +
  • CTRL-L-- Redraw the screen
    • +
  • C-- Choose a different CPU to examine in detail
    • +
  • X-- Extract organism and write a file of that organism
    • +
  • P-- Pause/Unpause a run
    • +
  • N-- Step forward one update
    • +
  • < and >-- Move to a different page in a given screen
    • +
  • arrow keys -- let you move around a map
    • +
+

Available key strokes are shown on the screen (note that the number of keys at the top screen will vary based on the width of the screen):

+

Map Screen shows each organism as colored charecter

+

Draft Documentation based on: "Avida User's Manual" C. Ofria, C.T. Brown, and C. Adami in Introduction to Artificial Life by C. Adami:

+

For the most part the text interface to Avida is simple and straightforward to use; most of the options available are listed on the screen. For example at all times there is a menu bar at the top of the screen which lists the current update and the keys to press to go to any of the most used Avida screens. These sections further explain each screen:

+

The Stats Screen

+

This screen displays all of the current statistics about the ongoing run. A typical snapshot of the screen looks like this:

+

Map Screen shows each organism as colored charecter

+

Starting at the upper left column of the screen the first block of statistics describes the current state of the soup. These statistics are defined as follows:

+
    +
  • Tot Births indicates the number of organisms which have been born during the past update.
    • +
  • Breed True is the total number of organisms currently in the soup which are exact copies of their parents
    • +
  • Parasites is the total number of organisms which have displayed parasitic behavior (i.e. the number which have executed instructions outside of their own memory).
    • +
  • Energy is the log of the ratio between the fitness of the dominant genotype and the average fitness in the soup.
    • +
  • Max Fitness is the highest fitness which can be found in the soup. During equilibrium this will usually be approximately the same as the fitness of the dominant genotype.
    • +
  • Max Merit is the highest merit which can be found in the soup. Since this gives no indication as to the replication abilities of this organism it is typically not a very revealing quantity.
    • +
+

To the right of the soup status column we have some information about the dominant genotype. This section simply lists the name of this genotype, its ID, its Species ID and its age (how many updates it has existed for). The first three of these statistics are purely for identification purposes.

+

On the right side of the screen more statistics are given for a number of common measurements on the dominant genotype as well as the average across all genotypes.

+

In the middle left side of the screen we have information about the various taxonomic levels in Avida; we give the current abundance of each in the Current column, the total number of each that have existed over the entire run in the Total column, the average number of updates each have existed in the Ave Age column and finally the entropy of each in the Entropy column.

+

Finally along the bottom of this screen we list the total number of organisms which have completed each of the assortment of tasks available in Avida. These numbers reflect only those organisms which have actually finished the task so even if every organism in the soup is capable of completing a task not all of them may be listed because the newborns would not have finished it for the first time.

+

The Histogram Screen

+

This screen is a histogram of the most abundant genotypes or species (use '

+

Histogram Screen shows a bar graph where showing the abundance of the 11 most common organisms

+

The first number here represents the fitness of the organism; this is the relative replication rate as compared to the other organisms in the population.

+

Next comes the name of the genotype (For example 096-aaacf). This is an identifier for the genotype and the name of the file it will be saved under if it is extracted. The number portion (before the dash) of the name is the length of the code for that genotype and the letter sequence after the dash gives a unique identifier for it. These are never repeated throughout a single run.

+

The repeated '#' after the name is the actual histogram; the number of characters which appear here is the relative current abundance of the genotype This allows quick recognition of which genotypes are dominant in the soup.

+

Finally each line ends with a number which is the exact abundance of organisms currently within this genotype.

+

If species information is being recorded (i.e. the SPECIES_RECORDING flag in the avida.cfg file is set to 1 or 2) the Genotype Abundance and Species Abundance Views might look like:

+

Histogram Screen shows a bar graph where showing the abundance of the 11 most common organisms

+

Notice that the '#' have been replaced with letters that represent the species of this genotype so any two lines with the same letter are of the same species.

+

Histogram Screen shows a bar graph where showing the abundance of the 11 most common species

+

The Environment Screen

+

This screen shows reactions and resources that are defined in the environment.cfg file. An example of the Reaction View:

+

Histogram Screen shows a bar graph where showing the abundance of the 11 most common organisms

+

One the left side of the main screen is a list of all the defined reactions. To the right is the number of organisms that have completed this reaction. Using the up and down arrow keys one of the reactions is highlighted. If there are any resources associated with the selected reaction they are displayed in the bottom pane.

+

The Resource View is similar:

+

Histogram Screen shows a bar graph where showing the abundance of the 11 most common organisms

+

In this case the resource names are shown with the inflow amount, outflow rate and total quantity of that resource in the environment. The reaction(s) associated with this resource are shown in the bottom pane.

+

The Options Screen

+

This screen lists all of the options which are both currently available and were used to initialize this run. A typical screen looks like:

+

+

The upper left corner of this screen gives information about the active genotype in the soup and the remainder of the upper portions of the screen list values from the avida.cfg file and what they were initialized to.

+

The lower part of the screen (within a box) shows the special options available to the user They are:

+

[H]istogram Screen: This will go to the histogram screen described above.

+

[B]lank Screen: This option will clear the screen making avida run marginally faster (since it will not be wasting much CPU time on the display).

+

[R]edraw Screen: If the screen gets garbled this will erase it and refresh all text which is supposed to appear.

+

[C]hoose New CPU: This option will put avida in map screen with the cursor on the screen Position the cursor over the CPU you would like to select and press enter. Additionally in the Windows version of avida the mouse can be used to select CPUs while in this screen. A single click highlights the CPU targeted and a double click selects it as the new active CPU and exits from this screen. The selected CPUs inner workings and genome can then be viewed in the Zoom screen (see below).

+

[E]xtract organism: This will save the genotype of the active organism (the one currently selected) to a file by the same name as the genotype An extracted organism will include all of its statistics as comments (gestation time fitness tasks completed etc) and can be loaded into another soup without modifying the file.

+

[P]ause: Freezes activity in the soup but still allows navigation through the interface and examination of the soup. Additionally many screens have additional options when the soup is paused.

+

[N]ext Update: When paused this will advance the soup a single update.

+

The Zoom Screen

+

This screen contains all of the information about the state of the active CPU has three views (CPU Stats Zoom, Component Zoom and Genotype Zoom). This screen is especially useful while avida is paused The space bar will cause the active organism to advance a single instruction and the return key will cause it to advance a full update In this way the execution of the organism can be fully examined.

+

CPU Stats Zoom View

+

Here is a typical screen shot:

+

Shows a screen with thirty or so variables and their values

+

The column on the left of the screen gives all of the current statistics for this CPU and the right of the screen contains information about the actual hardware in the CPU; the memory the stack the registers and the I/O buffers. The execution statistics recorded here are:

+
    +
  • GenotypID, Geno Name, SpeciesID: identifies the organism
    • +
  • Fitness: As described elsewhere fitness is the relative replication rate of this organism.
    • +
  • Gestation: This is the gestation time for the organism (the number of instructions it needs to execute in order to copy itself) If the organism has not copied itself a zero appears here.
    • +
  • Cur Merit: This is the merit which the organism is currently building during this gestation cycle Every time a new task is completed this value will increase appropriately When a divide occurs the current merit will be reset to its base value (typically the organism size)g and the value it was at before the divide will be used to determine how much CPU time it should get.
    • +
  • Flags: There are a number of flags within a CPU which can be set; a corresponding letter will appear in this field when this is the case The flags are A: Allocated (the organism has allocated memory for itself which it has not yet divided off) I: Injected (the organism was injected into the soup by the user) M: Mutated (an instruction has been struck by a point mutation) P: Parasite (the organism has executed code from within anothers memory) T: True Copy (the organism is an exact copy of its parent).
    • +
  • Location: The X/Y coordinate of the current organism
    • +
  • Facing or Executing: This attribute gives the direction in which the organism is pointed. Facing indicates that instructions which involve other organisms will use the organism at this X/Y coordinate while Executing means that the code in the specified organism is actually being run (parasitically) by this organism's CPU.
    • +
  • Age: The number of updates that this organism has lived.
    • +
  • Executed: The number of instructions this organism has executed since it was born.
    • +
  • Last Divide: The number of instructions this organism has executed since its last divide.
    • +
  • Offspring: The number of offspring which this organism has produced.
    • +
  • Thread: Current/Total threads
    • +
  • IP: Instruction pointer indicates the next site in the memory to be executed.
    • +
  • AX - CX: Content of the registers.
    • +
  • Stack: Content of the top element of the stack.
    • +
  • Memory: The current (and two following) instructions
    • +
+

Component Zoom View

+

Shows a screen with thirty or so variables and their values

+

This view consists of a number of panes that can be accessed by using the TAB key.

+

The top left pane shows the genome of the current organism. The number at the top box shows how many instructions are in the memory. The bottom box shows the individual instructions, if they are executate or were copied, and the location of the flow, write and read heads. Instructions can be edited here as well.

+

The top middle pane shows a miniature version of the map view around the current organism.

+

The bottom left pane shows the content of the registers, the Stack and the input values used by the organism.

+

The bottom right pane shows general information atou the organism

+

Genotype Zoom View

+

Shows a screen with thirty or so variables and their values

+ +

The Map Screen

+ +

The Map screen displays the spatial representation of the population of organisms in Avida. The grid itself is toroidal and typically will not fit entirely on the screen. You can use the arrow keys to adjust which part of the map appears on the screen. (On computers using a "curses" interface the arrow keys will often not function properly; instead, you can use the number keys 8, 2, 4 and 6 to move up, down, left and right respectively.) You reach the Map Screen by pressing the 'M' key.

+

Here is an example map screen (showing genotype view on a color terminal):

+

Map Screen shows each organism as colored character

+

Many different features can be displayed by the different map views. You can cycle through these views with the less-than and greater-than keys (< and >), as shown at the bottom-right of the map screen.

+

Genotype View: This view of displays the genotype of the organism at each location. Each organism is displayed as a hash mark ('#'); organisms with the same genotype have the same "color". (Hash marks might be bold; the bold version of a color represents a different genotype than the not-bold version. The bold and not-bold genotypes are not related in any particular way -- we're just using the bold versions as a way to get more "colors".)

+

As long as there are enough colors, each genotype has its own color, no matter how many or how few organisms have that genotype. When there are more genotypes than colors, the most abundant genotypes get their own colors, and all other genotypes are represented by a white not-bold hash mark (or by '+' if you cannot display color).Β  Which color is marking a genotype doesn't have any meaning at all.Β  (You can see the fitness, id, hash mark, and number of organisms for each of the most-abundant genotypes on the Histogram Screen, which you can reach by pressing the 'H' key.)

+

Breed True View: This view simply displays a bold or not-bold hash mark ('*' or '-' if you can't display colors) for each organism, indicating whether it is an exact copy of its mother (bold white hash mark, or '*') or not (normal white hash mark, or '-').

+

Parasite View: This view displays a bold or not-bold white hash mark ('*' or '-' if you can't display color) for each organism, indicating whether it is a parasite (bold white hash mark, or '*') or not (normal white hash mark, or '-').

+

Forager View: If you know what this view shows, please edit this page!

+

Avatar View: If you know what this view shows, please edit this page!

+

Territory View: If you know what this view shows, please edit this page!

+

Mutation View: This view displays a bold or not-bold white hash mark ('*' or '-' if you can't display color) for each organism, indicating whether it has been hit by mutations (bold white hash mark, or '*') or not (normal white hash mark, or '-').

+

Thread View: This view displays the number of the thread that each organism is currently executing. For runs where organisms have only one thread (which is typical), all the numbers will be 1.

+

Modified View: If you know what this view shows, please edit this page!

+

Lineage View: This view displays the lineage of the organism at each location; each color corresponds to a single lineage. (Presumably the choice of colors and what happens when there are more lineages than colors is very similar to the way colors are handled in Genotype View.)

+ +

The Histogram Screen

+ +

This screen is a histogram of the most abundant genotypes or species (use '

+

Histogram Screen shows a bar graph where showing the abundance of the 11 most common organisms

+

The first number here represents the fitness of the organism; this is the relative replication rate as compared to the other organisms in the population.

+

Next comes the name of the genotype (For example 096-aaacf) This is an identifier for the genotype and the name of the file it will be saved under if it is extracted The number portion (before the dash) of the name is the length of the code for that genotype and the letter sequence after the dash gives a unique identifier for it These are never repeated throughout a single run.

+

The repeated '#' after the name is the actual histogram; the number of characters which appear here is the relative current abundance of the genotype This allows quick recognition of which genotypes are dominant in the soup.

+

Finally each line ends with a number which is the exact abundance of organisms currently within this genotype.

+

If species information is being recorded (i.e. the SPECIES_RECORDING flag in the avida.cfg file is set to 1 or 2) the Genotype Abundance and Species Abundance Views might look like:

+

Histogram Screen shows a bar graph where showing the abundance of the 11 most common organisms

+

Notice that the '#' have been replaced with letters that represent the species of this genotype so any two lines with the same letter are of the same species.

+

Histogram Screen shows a bar graph where showing the abundance of the 11 most common species

\ No newline at end of file diff --git a/docs/documentation/Time-slicing-settings.md b/docs/documentation/Time-slicing-settings.md new file mode 100644 index 0000000..73e8df4 --- /dev/null +++ b/docs/documentation/Time-slicing-settings.md @@ -0,0 +1,27 @@ +

These settings describe exactly what an update is, and how CPU time is allocated to organisms during that update.

+ + + + + + + + + + + + + + + + + + + + + + + +
AVE_TIME_SLICEThis sets the average number of instructions an organism should execute each update. Organisms with a low merit will consistently obtain fewer, while organisms of a higher merit will receive more.
SLICING_METHODThis setting determines the method by which CPU time is handed out to the organisms. Method 0 ignores merit, and hands out time on the CPU evenly; each organism executes one instruction for the whole population before moving onto the second. Method 1 is probabilistic; each organism has a chance of executing the next instruction proportional to it merit. This method is slow due to the large number of random values that need to be obtained and evaluated (and it only gets slower as merits get higher). Method 2 is fully integrated; the organisms get CPU time proportional to their merit, but in a fixed, deterministic order.
BASE_MERIT_METHODThis setting determines the base value of an organism's merit. Merit is typically proportional to genome length otherwise there is a strong selective pressure for shorter genomes (shorter genome => less to copy => reduced copying time => replicative advantage). Unfortunately, organisms will cheat if merit is proportional to the full genome length -- they will add on unexecuted and uncopied code to their genomes creating a code bloat. This isn't the most elegant fix, but it works.
MAX_LABEL_EXE_SIZELabels are sequences of nop (no-operation) instructions used only to modify the behavior of other instructions. Quite often, an organism will have these labels in their genomes where the nops are used by another instruction, but never executed directly. To represent the executed length of an organism correctly, we need to somehow count these labels. Unfortunately, if we count the entire label, the organisms will again "cheat" artificially increasing their length by growing huge labels. This setting limits the number of nops that are counted as executed when a label is used.
MAX_CPU_THREADSDetermines the number of simultaneous processes that an organism can run. That is, basically, the number of things it can do at once. This setting is meaningless unless threads are supported in the virtual hardware and the instructions are available within the instruction set.
+ +See the avida.cfg file for more options: SLICING_BURST_SIZE, BASE_CONST_MERIT, MERIT_BONUS_INST, MERIT_BONUS_EFFECT, FITNESS_VALLEY, FITNESS_VALLEY_START, FITNESS_VALLEY_STOP, DEFAULT_BONUS, MERIT_DEFAULT_BONUS, MERIT_INC_APPLY_IMMEDIATE, TASK_REFRACTORY_PERIOD, FITNESS_METHOD, FITNESS_COEFF_1, FITNESS_COEFF_2, THREAD_SLICING_METHOD, NO_CPU_CYCLE_TIME, PRECALC_PHENOTYPE, FASTFORWARD_UPDATES, FASTFORWARD_NUM_ORGS, and GENOTYPE_PHENPLAST_CALC. diff --git a/docs/documentation/Topology-settings.md b/docs/documentation/Topology-settings.md new file mode 100644 index 0000000..d2fb7f3 --- /dev/null +++ b/docs/documentation/Topology-settings.md @@ -0,0 +1,12 @@ +This section covers all of the basic topology variables that describe the structure of the world. + + + + + + + + +
WORLD_X
WORLD_Y 		The settings determine the size of the Avida grid that the organisms populate; the world consists of WORLD_X * WORLD_Y cells. In mass action mode the shape of the grid is not relevant, only the number of organisms that are in it.
+ +See the avida.cfg file for more settings: WORLD_GEOMETRY, SCALE_FREE, SCALE_FREE_ALPHA, and SCALE_FREE_ZERO_APPEAL. diff --git a/docs/documentation/Using-mating-types-(separate-sexes).mediawiki b/docs/documentation/Using-mating-types-(separate-sexes).mediawiki new file mode 100644 index 0000000..f158d47 --- /dev/null +++ b/docs/documentation/Using-mating-types-(separate-sexes).mediawiki @@ -0,0 +1,66 @@ +

Using sexual reproduction with mating types

+

Although by default, reproduction in Avida is asexual, Avida can be configured to allow organisms to reproduce with sexual reproduction. By default, when sexual reproduction is turned on, any organism can mate with any other organism. However, Avida is also capable of sexual reproduction with two distinct mating types (e.g., males and females), mimicking the mating systems found in many biological organisms, in which only matings between opposite mating types are successful. (Note: this page is intended as an overview of how to implement these distinct mating types and their associated configuration options, not as an exhaustive guide to all of the other options involved in sexual reproduction in general).

+


First, you will need to turn on mating types in avida.cfg:

+

MATING_TYPES 1

+

However, this change by itself is not enough. You will also need to modify your instruction set so that the organisms can set their mating types, by adding the following two instructions to your instruction set:

+

INST set-mating-type-male
INST set-mating-type-female

+

Once an organism sets its mating type, it is irreversible -- repeated execution of a different set-mating-type-X instruction will fail. If you want your organisms to be able to change their mating type during their lifetime, you can add another instruction that lets them de-differentiate, after which they can re-set their mating type to something else:

+

INST set-mating-type-juvenile

+

Then, you also need to make sure that your organisms are using the proper instruction to divide, or else their mating types may not be checked properly. So you should replace the divide instruction in your instruction set (probably h-divide or divide-sex) with div-sex-mating-type.

+

While we're in the instruction set, you might want to consider adding instructions allowing organisms to conditionally execute instructions based on their phenotypic sex (otherwise, they have no real mechanism to detect what their phenotypic sex is):

+

INST if-mating-type-male
INST if-mating-type-female
INST if-mating-type-juvenile

+

Next, you'll need to modify your events file to make sure that the population is initialized with a male and a female organism. You can create a new default organism by modifying default-heads-sex.org (make two, say, default-heads-sex-male.org and default-heads-sex-female.org). Simple add a set-mating-type-male or set-mating-type-female instruction to the beginning of each .org file (you'll probably want it to be the first instruction that they execute, but it doesn't necessarily have to be). Then replace the original divide instruction with the div-sex-mating-type instruction.

+

Now, modify your events file to inject both organisms at the start of the run:

+

u begin Inject default-heads-sex-male.org 0
u begin Inject default-heads-sex-female.org 1

+

At this point, you should be able to get a run going, but read on for some further options and points to consider.

+

-------------------------------------------

+

What happens during sexual reproduction:

+

When an organism reproduces sexually, it needs to find a mate. When the first organism in the population successfully divides, its 'offspring' goes into what is called the birth chamber, rather than being placed into the population. This is sort of a waiting area in which organisms can find mates. When another organism divides, Avida checks the birth chamber to see if there are any 'offspring' waiting to find a mate that were generated by a parent of the opposite mating type. If so, then they recombine, and the sexual offspring are placed into the population. If not, then this organism's 'offspring' goes into the birth chamber to wait as well. Because of this waiting process, you can almost think of these 'offspring' as being more like sperm or eggs, that need to join up with a gamete of the opposite type before they can form a zygote together.

+

There are a few options regarding the birth chamber. First, you'll want to set its maximum size -- how many 'offspring' (or gametes) can be waiting in the birth chamber at any given time? The default is 3600, the same as the size of the default population. This can be changed in avida.cfg:

+

MAX_GLOBAL_BIRTH_CHAMBER_SIZE 3600

+

Another thing to consider regarding the birth chamber is how long 'offspring' or gametes can wait there before dying. The default setting for this parameter (MAX_BIRTH_WAIT_TIME) is -1, meaning there is no limit -- they will remain in the birth chamber indefinitely, until they get picked by a mate. You will almost certainly want to change this. For example:

+

MAX_BIRTH_WAIT_TIME 3

+

would tell Avida that an 'offspring' or gamete can wait for three updates to be chosen as a mate, but any gametes that are not picked as mates within three updates after they go into the birth chamber will die. In practice, three seems to give good results.

+

One final thing to consider is spatial organization. Currently, the birth chamber has no spatial organization to it; any organism can mate with any other organism regardless of their "physical" location in the population. Since mating has no spatial structure, you therefore may not want any spatial structure in your population at all. To do so, change:

+

BIRTH_METHOD 4

+

-------------------------------------------

+

Mate choice:

+

By default, organisms will choose mates randomly. However, organisms can choose mates based on various phenotypic attributes by executing instructions that confer certain mating preferences. To enable this, simply add one or more of the following instructions to the instruction set:

+

INST set-mate-preference-highest-merit
INST set-mate-preference-random
INST set-mate-preference-highest-display-a
INST set-mate-preference-highest-display-b

+

For example, suppose a female organism executes a set-mate-preference-highest-merit instruction, and then later divides. If there is more than one male 'offspring' (or sperm) waiting in the birth chamber when she divides, she will pick the one that came from a parent with the highest merit. Likewise, a female that has declared a preference for males with higher values of display A will select the one with the highest value of display A from among the available offspring of males in the birth chamber at the time of her divide.

+

But wait -- what are these displays? Organisms can develop displays by executing instructions, which you will have to add to the instruction set:

+

increment-mating-display-a
increment-mating-display-b
set-mating-display-a
set-mating-display-b

+

When an organism is born, its value for both display A and display B are both set to 0. Executing an increment-mating-display-A instruction adds 1 unit to its display. Using this method, an organism can only develop a large display by repeatedly executing this increment instruction. The set-mating-display-A and -B instructions, on the other hand, will copy the value of the ?BX? register (which register is used can be nop-modified) into its mating display. So using these instructions, organisms can develop exaggerated displays relatively quickly by using mathematical operations to generate a large value in their registers and then copying it to their displays.

+

Of course, in nature, organisms don't always perceive signals with 100% accuracy. Thus, in Avida, you can introduce noise into an organism's perception of other organisms' signals or phenotypic traits, using the NOISY_MATE_ASSESSMENT config option (0 = noise off [default]; 1 = noise on):

+

NOISY_MATE_ASSESSMENT 1

+

How much noise is introduced? When an organism assesses a phenotypic trait of a potential mate, the perceived value is drawn from a normal distribution with the mean at the actual value, and with a coefficient of variation of 0.1. This coefficient of variation can be changed with the MATE_ASSESSMENT_CV config option:

+

MATE_ASSESSMENT_CV 0.15

+

-------------------------------------------

+

Costs:

+

In nature, males and females of many animals can differ in certain traits because of sex-specific selective pressures. Avida can reflect this by implementing sex-specific costs for instructions. For example, in many animals, females invest more in reproduction. In Avida, we can make females pay extra CPU cycles to execute an instruction. This is an especially important consideration for the div-sex-mating-type instruction. Making females pay extra CPU cycles to complete division not only reflects the biological characteristics of many species, but also slows down female reproductive rates. As a result of males dividing more quickly than females (on average), the offspring of male organisms (i.e., sperm) will accumulate in the birth chamber. Females, then, will usually not be mate-limited, and will have more opportunities for mate choice -- again reflecting patterns that are often seen in nature. You can do this as follows, by modifying the div-sex-mating-types instruction in the instruction set file:

+

INST div-sex-mating-type:female_cost=50

+

This will require females to pay an extra 50 CPU cycles to complete their divide statements. Note that another work-around to forcing females to be the choosy sex is with the LEKKING option in avida.cfg. If you set its value to 1, all the offspring of male organisms will always go into the birth chamber -- in other words, males can never choose females as mates; females are always the 'choosers'.

+

Another important element is the cost of mate choice. In nature, mate choice can impose substantial costs on organisms. (For example, spending a lot of time searching for mates rather than mating with the first guy that comes along can put you at greater risk of being eaten by a predator.) You can force females who mate non-randomly to pay even greater CPU costs as follows:

+

INST div-sex-mating-type:female_cost=50:choosy_female_cost=50

+

In this setup, males will pay 1 CPU cycle for executing a div-sex-mating-type instruction. Randomly mating females will pay an additional 50 CPU cycles. Females who mate non-randomly (e.g., choose the male with the highest merit or highest display A) will pay another 50 on top of that (i.e., 1 + 50 [for being female] + 50 [for being choosy] = 101).

+


-------------------------------------------

+

Memory considerations:

+

Normally, Avida keeps a record of every genotype (i.e., genome sequence) that has ever existed in the population. This is very useful when you want to trace an organism's lineage back through its ancestors. However, when sexual reproduction is turned on (and especially when separate mating types are turned on), all that recombination generates much more diversity. This means that Avida can take up quite a bit of memory (and will probably crash if you're doing a long run), and will get slower and slower as the run progresses and there are more and more genotypes to keep track of.

+

If you don't need detailed information on organismal ancestry, you can turn off lineage tracking with the following config setting:

+

DISABLE_GENOTYPE_CLASSIFICATION 1

+


-------------------------------------------

+

Collecting data on mating types:

+

There are a variety of print actions that can be used to gather data on mating types and mate preferences as your population evolves:

+

PrintMatingTypeHistogram: This action will print the number of juvenile, female, and male organisms in the population at the current update

+

PrintMatingDisplayData: This action prints the average display values (display-A and display-B) of all of the juveniles, females, and males in the population at the current update

+

PrintFemaleMatePreferenceData: This action prints the number of females with each different type of mating preference at the current update

+

PrintBirthChamberMatingTypeHistogram: This action prints the number of "sperm" and "eggs" in the birth chamber at the current update

+

PrintSuccessfulMates: This action prints the genotypes and some useful phenotypic information (e.g., merit, mating types, displays, preferences) of the parents of all the successful matings that occurred during the current update

+

PrintBirthChamber: This action prints the genotypes and some useful phenotypic information (e.g., merit, mating types, displays, preferences) of the parents of all the "sperm" or "eggs" waiting in the birth chamber at the current update

+

(Note: by using PrintBirthChamber to print all the organisms currently waiting to be chosen as mates, and PrintSuccessfulMates to print all the organisms that were successfully chosen as mates, you can estimate sexual selection differentials.)

+

-------------------------------------------

+

Analyze Mode

+

There are a few phenotypic attributes that can be used with the DETAIL statement in analyze mode (pretty self-explanatory):

+

mating_type
mate_preference
mating_display_a
mating_display_b

+

Using these, you can take a genotype and run it through analyze mode to find out what mating type it develops as (useful if there are multiple set-mating-type-XXX instructions in a genome and it's hard to tell which one will be executed first), what kind of mate preference it will exhibit, how large its sexual displays are, etc.

+

 

diff --git a/docs/documentation/glossary/Glossary--Bitwise.md b/docs/documentation/glossary/Glossary--Bitwise.md new file mode 100644 index 0000000..e6be4b1 --- /dev/null +++ b/docs/documentation/glossary/Glossary--Bitwise.md @@ -0,0 +1,6 @@ + +Other Notation : Bitwise + +

Bitwise

+ +A bitwise operation is one in which each bit is treated independently of all the other bits in a number. Thus if a logical AND was performed between two bitstrings, the first bit of the first string would be ANDed to the first bit in the second string, the second bit to the second bit and so on. diff --git a/docs/documentation/glossary/Glossary--CPU-cycle.md b/docs/documentation/glossary/Glossary--CPU-cycle.md new file mode 100644 index 0000000..63d6386 --- /dev/null +++ b/docs/documentation/glossary/Glossary--CPU-cycle.md @@ -0,0 +1,6 @@ + +Other Notation : CPU-cycle + +

CPU-cycle

+ +A CPU-cycle is the amount of time it takes the CPU of an organism to execute a single instruction in its memory. CPU-cycles can be thought of as the primary resource in the avida system; more cycles per unit time allow a more rapid expression of the organism's genome. diff --git a/docs/documentation/glossary/Glossary--CPU.md b/docs/documentation/glossary/Glossary--CPU.md new file mode 100644 index 0000000..3c108e1 --- /dev/null +++ b/docs/documentation/glossary/Glossary--CPU.md @@ -0,0 +1,6 @@ + +CPU Components : CPU + +

CPU

+ +Each individual organism in an avida population has its own virtual central processing unit (CPU) that executes its genome. An avida CPU consists of a memory space with four heads pointing to specific locaitions in that memory, three registers, two stacks, and input and output buffers. diff --git a/docs/documentation/glossary/Glossary--Complement-Label.md b/docs/documentation/glossary/Glossary--Complement-Label.md new file mode 100644 index 0000000..b0a84f8 --- /dev/null +++ b/docs/documentation/glossary/Glossary--Complement-Label.md @@ -0,0 +1,10 @@ + +Other Notation : Complement-Label + +

Complement-Label

+ +The complement of a label is found by taking each +no-operation instruction that makes up that label, +and shifting it to the next in alphabetical order, looping around at the end. +Thus, in the default instruction set, nop-A -> nop-B -> nop-C -> nop-A. The label +"nop-B nop-A nop-C nop-C" has the complement "nop-C nop-B nop-A nop-A". diff --git a/docs/documentation/glossary/Glossary--Genome.md b/docs/documentation/glossary/Glossary--Genome.md new file mode 100644 index 0000000..c6ae70a --- /dev/null +++ b/docs/documentation/glossary/Glossary--Genome.md @@ -0,0 +1,6 @@ + +CPU Components : Genome + +

Genome

+ +The genome of an organism is the original, underlying program that controls the behavior of that organism. The memory space in the CPU of that organism is initialized to the genome, but will change with time. A genotype is is determined by a unique genome sequence. diff --git a/docs/documentation/glossary/Glossary--Genotype.md b/docs/documentation/glossary/Glossary--Genotype.md new file mode 100644 index 0000000..a23d375 --- /dev/null +++ b/docs/documentation/glossary/Glossary--Genotype.md @@ -0,0 +1,6 @@ + +Other Notation : Genotype + +

Genotype

+ +A genotype is a unique sequence of instructions that make up a genome of an organism. Any two organisms with identical genomes are considered to be the same genotype. diff --git a/docs/documentation/glossary/Glossary--Heads.md b/docs/documentation/glossary/Glossary--Heads.md new file mode 100644 index 0000000..82ae7d2 --- /dev/null +++ b/docs/documentation/glossary/Glossary--Heads.md @@ -0,0 +1,6 @@ + +CPU Components : Heads + +

Heads

+ +Each CPU has four heads associated with it. The first is the instruction pointer (IP) which determines the next instruction to be executed by the CPU. After each execution, the IP is automaticall advanced (unless the instruction executed dictates otherwise). The second is the read-head (RH), which determines what instruction is copied from a copy command, and then the write-head (WH) determines the position it is copied to. Finally, the flow-head (FH) is used to mark positions in the genome to move the other heads to. The flow-head is commonly used to mark the beginning of a loop to jump the IP back to from the loop's end. diff --git a/docs/documentation/glossary/Glossary--IO.md b/docs/documentation/glossary/Glossary--IO.md new file mode 100644 index 0000000..44b2f5e --- /dev/null +++ b/docs/documentation/glossary/Glossary--IO.md @@ -0,0 +1,6 @@ + +Instruction : IO + +

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?. diff --git a/docs/documentation/glossary/Glossary--Input-Output.md b/docs/documentation/glossary/Glossary--Input-Output.md new file mode 100644 index 0000000..8e0c52c --- /dev/null +++ b/docs/documentation/glossary/Glossary--Input-Output.md @@ -0,0 +1,6 @@ + +CPU Components : Input-Output + +

Input-Output

+ +Each CPU in avida is supplied with 3 input values of 32 bits each. The IO instruction is used by the organisms to get the an input (cyclying through the three options) into a register and to output numbers from a register. Each ouput is compared to all inputs to determing if any tasks (by default, specified logical computations) have been performed by the organism. diff --git a/docs/documentation/glossary/Glossary--Instruction.md b/docs/documentation/glossary/Glossary--Instruction.md new file mode 100644 index 0000000..621aebe --- /dev/null +++ b/docs/documentation/glossary/Glossary--Instruction.md @@ -0,0 +1,6 @@ + +CPU Components : Instruction + +

Instruction

+ +Each position in an organisms genome or a CPUs memory consists of an instruction. Each instruction is associated with a specific function on the CPU when it is executed (expressed); in series these instructions lead to all of the complex behaviors of the organisms. diff --git a/docs/documentation/glossary/Glossary--Label.md b/docs/documentation/glossary/Glossary--Label.md new file mode 100644 index 0000000..c5ef87e --- /dev/null +++ b/docs/documentation/glossary/Glossary--Label.md @@ -0,0 +1,12 @@ + +Other Notation : Label + +

Label

+ +A label (sometimes called a template -- for example, in biology) is a sequence of +no-operation instructions used to mark +regions of code within a genome. Some instructions +(such a h-search) are followed by a label; the +complement of that label is then used +to match against other labels. See the descriptions of the individual +instructions for how they use labels. diff --git a/docs/documentation/glossary/Glossary--Logic.md b/docs/documentation/glossary/Glossary--Logic.md new file mode 100644 index 0000000..5f58bbd --- /dev/null +++ b/docs/documentation/glossary/Glossary--Logic.md @@ -0,0 +1,6 @@ + +Other Notation : Logic + +

Logic

+ +A logic operation has as inputs a collection of bits, and as an output a single bit. The operation itself is a unique map from the input bits to the output bits. In avida, a logic operation is done in a bitwise fashion, so that the operation is effectively performed 32 times when a reward is granted. diff --git a/docs/documentation/glossary/Glossary--Memory.md b/docs/documentation/glossary/Glossary--Memory.md new file mode 100644 index 0000000..2e94195 --- /dev/null +++ b/docs/documentation/glossary/Glossary--Memory.md @@ -0,0 +1,6 @@ + +CPU Components : Memory + +

Memory

+ +A CPU contains a memory space to hold a sequence of instructions to be executed. The memory space is initialize to the genome of the organism, but it will be modified over the lifetime of the organism, typically as an offspring is produced. As section of the memory is then divided off to initialize the ofpspring. diff --git a/docs/documentation/glossary/Glossary--Mutation.md b/docs/documentation/glossary/Glossary--Mutation.md new file mode 100644 index 0000000..69ee2e1 --- /dev/null +++ b/docs/documentation/glossary/Glossary--Mutation.md @@ -0,0 +1,6 @@ + +Other Notation : Mutation + +

Mutation

+ +A mutation is a random change of an instruction from the genome of an organism. There are three main times that mutations can occur; point mutations will happen randomly through time, with and equal probability at every site, copy mutations occur when a site is actively being copied, and divide mutations occur when an organim is splitting off an offspring. diff --git a/docs/documentation/glossary/Glossary--Nop-Head-Notation.md b/docs/documentation/glossary/Glossary--Nop-Head-Notation.md new file mode 100644 index 0000000..cea3907 --- /dev/null +++ b/docs/documentation/glossary/Glossary--Nop-Head-Notation.md @@ -0,0 +1,6 @@ + +Other Notation : Nop-Head-Notation + +

Nop-Head-Notation

+ +A head abbreviation (IP, RH, WH, or FH) surrounded by question marks refers to that head being used as a default, when the instruction in question is being executed, but if the instruction is followed by a no-operation (nop) instruction, the nop will alter the register used. A nop-A instruction indicates the instruction pointer (IP), nop-B is the read-head (RH), nop-C is the write-head (WH), and there is no way to use the flow-head (FH) unless it is by default. diff --git a/docs/documentation/glossary/Glossary--Nop-Register-Notation.md b/docs/documentation/glossary/Glossary--Nop-Register-Notation.md new file mode 100644 index 0000000..582233f --- /dev/null +++ b/docs/documentation/glossary/Glossary--Nop-Register-Notation.md @@ -0,0 +1,6 @@ + +Other Notation : Nop-Register-Notation + +

Nop-Register-Notation

+ +A register name (AX, BX, or CX) surrounded by question marks refers to that register being used by default when the instruction in question is being executed, but if the instruction is followed by a no-operation (nop) instruction, the nop will alter the register used. A nop-A instruction indicates AX, nop-B is BX, and nop-C is CX. diff --git a/docs/documentation/glossary/Glossary--Organism.md b/docs/documentation/glossary/Glossary--Organism.md new file mode 100644 index 0000000..2cdf293 --- /dev/null +++ b/docs/documentation/glossary/Glossary--Organism.md @@ -0,0 +1,6 @@ + +Other Notation : Organism + +

Organism

+ +An organism in avida consists of a unique genome and a CPU that expresses (executes) the code in that genome. A population in avida is a collection of these organisms. diff --git a/docs/documentation/glossary/Glossary--Population.md b/docs/documentation/glossary/Glossary--Population.md new file mode 100644 index 0000000..dc30001 --- /dev/null +++ b/docs/documentation/glossary/Glossary--Population.md @@ -0,0 +1,6 @@ + +Other Notation : Population + +

Population

+ +A population in avida is a collection of digital organisms that interact and evolve over time. diff --git a/docs/documentation/glossary/Glossary--Registers.md b/docs/documentation/glossary/Glossary--Registers.md new file mode 100644 index 0000000..5a632b3 --- /dev/null +++ b/docs/documentation/glossary/Glossary--Registers.md @@ -0,0 +1,10 @@ + +CPU Components : Registers + +

Registers

+ +

+A register is a storage space for a single number. +Each classic CPU in Avida contains three registers, each of which is made up of 32 bits. All math-based instructions opperate on the registers, and various instruction will move the values in the registers around. +

+ diff --git a/docs/documentation/glossary/Glossary--Stack.md b/docs/documentation/glossary/Glossary--Stack.md new file mode 100644 index 0000000..1363c4d --- /dev/null +++ b/docs/documentation/glossary/Glossary--Stack.md @@ -0,0 +1,8 @@ + +CPU Components : Stack + +

Stack

+

+Each classic CPU in Avida has two stacks used for storage of numbers. The push and pop instructions are used to move numbers between the registers and the stack, and the swap-stk instruction toggles the active stack in use. +

+ diff --git a/docs/documentation/glossary/Glossary--Tasks.md b/docs/documentation/glossary/Glossary--Tasks.md new file mode 100644 index 0000000..7fac88f --- /dev/null +++ b/docs/documentation/glossary/Glossary--Tasks.md @@ -0,0 +1,6 @@ + +Other Notation : Tasks + +

Tasks

+ +The organisms in avida are granted extra CPU-cycles for performing specific computations. Every time an organisms outputs a number, it is examined against the inputs to determine if any tasks have been compleated. If the number of extra CPU-cycles outweigh the number used to perform the task, the computation will typically be reinforced through natural selection. By default, the tasks in avida are all logic operations that act upon the inputs in a bitwise fashion. diff --git a/docs/documentation/glossary/Glossary--add.md b/docs/documentation/glossary/Glossary--add.md new file mode 100644 index 0000000..f18779c --- /dev/null +++ b/docs/documentation/glossary/Glossary--add.md @@ -0,0 +1,7 @@ + +Instruction : add + +

add

+ +

This instruction reads in the contents of the BX and CX registers and sums them together. The result of this operation is then placed in the ?BX? register.

+ diff --git a/docs/documentation/glossary/Glossary--dec.md b/docs/documentation/glossary/Glossary--dec.md new file mode 100644 index 0000000..72e0daa --- /dev/null +++ b/docs/documentation/glossary/Glossary--dec.md @@ -0,0 +1,6 @@ + +Instruction : dec + +

dec

+ +This instruction reads in the contents of the ?BX? register and decrements it by one. diff --git a/docs/documentation/glossary/Glossary--h-alloc.md b/docs/documentation/glossary/Glossary--h-alloc.md new file mode 100644 index 0000000..f4fb0ac --- /dev/null +++ b/docs/documentation/glossary/Glossary--h-alloc.md @@ -0,0 +1,6 @@ + +Instruction : h-alloc + +

h-alloc

+ +This instruction allocates additional memory for the organism up to the maximum it is allowed to use for its offspring. diff --git a/docs/documentation/glossary/Glossary--h-copy.md b/docs/documentation/glossary/Glossary--h-copy.md new file mode 100644 index 0000000..01fc606 --- /dev/null +++ b/docs/documentation/glossary/Glossary--h-copy.md @@ -0,0 +1,6 @@ + +Instruction : h-copy + +

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. diff --git a/docs/documentation/glossary/Glossary--h-divide.md b/docs/documentation/glossary/Glossary--h-divide.md new file mode 100644 index 0000000..8bf72f2 --- /dev/null +++ b/docs/documentation/glossary/Glossary--h-divide.md @@ -0,0 +1,6 @@ + +Instruction : h-divide + +

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. diff --git a/docs/documentation/glossary/Glossary--h-search.md b/docs/documentation/glossary/Glossary--h-search.md new file mode 100644 index 0000000..c12e201 --- /dev/null +++ b/docs/documentation/glossary/Glossary--h-search.md @@ -0,0 +1,6 @@ + +Instruction : h-search + +

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. diff --git a/docs/documentation/glossary/Glossary--if-label.md b/docs/documentation/glossary/Glossary--if-label.md new file mode 100644 index 0000000..5285498 --- /dev/null +++ b/docs/documentation/glossary/Glossary--if-label.md @@ -0,0 +1,6 @@ + +Instruction : if-label + +

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. diff --git a/docs/documentation/glossary/Glossary--if-less.md b/docs/documentation/glossary/Glossary--if-less.md new file mode 100644 index 0000000..94b6922 --- /dev/null +++ b/docs/documentation/glossary/Glossary--if-less.md @@ -0,0 +1,6 @@ + +Instruction : if-less + +

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. diff --git a/docs/documentation/glossary/Glossary--if-n-equ.md b/docs/documentation/glossary/Glossary--if-n-equ.md new file mode 100644 index 0000000..184c868 --- /dev/null +++ b/docs/documentation/glossary/Glossary--if-n-equ.md @@ -0,0 +1,6 @@ + +Instruction : if-n-equ + +

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. diff --git a/docs/documentation/glossary/Glossary--inc.md b/docs/documentation/glossary/Glossary--inc.md new file mode 100644 index 0000000..7ffba09 --- /dev/null +++ b/docs/documentation/glossary/Glossary--inc.md @@ -0,0 +1,6 @@ + +Instruction : inc + +

inc

+ +This instruction reads in the contents of the ?BX? register and increments it by one diff --git a/docs/documentation/glossary/Glossary--jmp-head.md b/docs/documentation/glossary/Glossary--jmp-head.md new file mode 100644 index 0000000..d4a3c8c --- /dev/null +++ b/docs/documentation/glossary/Glossary--jmp-head.md @@ -0,0 +1,6 @@ + +Instruction : jmp-head + +

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. diff --git a/docs/documentation/glossary/Glossary--mov-head.md b/docs/documentation/glossary/Glossary--mov-head.md new file mode 100644 index 0000000..3446341 --- /dev/null +++ b/docs/documentation/glossary/Glossary--mov-head.md @@ -0,0 +1,6 @@ + +Instruction : mov-head + +

mov-head

+ +This instruction will cause the ?IP? to jump to the position in memory of the flow-head. diff --git a/docs/documentation/glossary/Glossary--nand.md b/docs/documentation/glossary/Glossary--nand.md new file mode 100644 index 0000000..449a690 --- /dev/null +++ b/docs/documentation/glossary/Glossary--nand.md @@ -0,0 +1,6 @@ + +Instruction : nand + +

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. diff --git a/docs/documentation/glossary/Glossary--nop-instructions.md b/docs/documentation/glossary/Glossary--nop-instructions.md new file mode 100644 index 0000000..7ba8591 --- /dev/null +++ b/docs/documentation/glossary/Glossary--nop-instructions.md @@ -0,0 +1,6 @@ + +Instruction : nop-instructions + +

nop-instructions

+ +The instructions nop-A, nop-B, and nop-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. diff --git a/docs/documentation/glossary/Glossary--pop.md b/docs/documentation/glossary/Glossary--pop.md new file mode 100644 index 0000000..ad5007f --- /dev/null +++ b/docs/documentation/glossary/Glossary--pop.md @@ -0,0 +1,6 @@ + +Instruction : pop + +

pop

+ +This instruction removes the top element from the active stack, and places it into the ?BX? register. diff --git a/docs/documentation/glossary/Glossary--push.md b/docs/documentation/glossary/Glossary--push.md new file mode 100644 index 0000000..7d84fa7 --- /dev/null +++ b/docs/documentation/glossary/Glossary--push.md @@ -0,0 +1,6 @@ + +Instruction : push + +

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. diff --git a/docs/documentation/glossary/Glossary--set-flow.md b/docs/documentation/glossary/Glossary--set-flow.md new file mode 100644 index 0000000..84466dc --- /dev/null +++ b/docs/documentation/glossary/Glossary--set-flow.md @@ -0,0 +1,6 @@ + +Instruction : set-flow + +

set-flow

+ +This instruction moves the flow-head to the memory position denoted in the ?CX? register. diff --git a/docs/documentation/glossary/Glossary--shift-l.md b/docs/documentation/glossary/Glossary--shift-l.md new file mode 100644 index 0000000..1fd6ce5 --- /dev/null +++ b/docs/documentation/glossary/Glossary--shift-l.md @@ -0,0 +1,6 @@ + +Instruction : shift-l + +

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. diff --git a/docs/documentation/glossary/Glossary--shift-r.md b/docs/documentation/glossary/Glossary--shift-r.md new file mode 100644 index 0000000..37256e7 --- /dev/null +++ b/docs/documentation/glossary/Glossary--shift-r.md @@ -0,0 +1,6 @@ + +Instruction : shift-r + +

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. diff --git a/docs/documentation/glossary/Glossary--sub.md b/docs/documentation/glossary/Glossary--sub.md new file mode 100644 index 0000000..5ee3198 --- /dev/null +++ b/docs/documentation/glossary/Glossary--sub.md @@ -0,0 +1,6 @@ + +Instruction : sub + +

sub

+ +This instruction reads in the contents of the BX and CX registers and subtracts CX from BX. The result of this operation is then placed in the ?BX? register. diff --git a/docs/documentation/glossary/Glossary--swap-stk.md b/docs/documentation/glossary/Glossary--swap-stk.md new file mode 100644 index 0000000..3b802a5 --- /dev/null +++ b/docs/documentation/glossary/Glossary--swap-stk.md @@ -0,0 +1,6 @@ + +Instruction : swap-stk + +

swap-stk

+ +This instruction toggles the active stack in the CPU. All other instructions that use a stack will always use the active one. diff --git a/docs/documentation/glossary/Glossary--swap.md b/docs/documentation/glossary/Glossary--swap.md new file mode 100644 index 0000000..6aa07fa --- /dev/null +++ b/docs/documentation/glossary/Glossary--swap.md @@ -0,0 +1,6 @@ + +Instruction : swap + +

swap

+ +This instruction swaps the contents of the ?BX? register with its complement. diff --git a/docs/documentation/images/AvidaLogo.gif b/docs/documentation/images/AvidaLogo.gif new file mode 100644 index 0000000..2f9727f Binary files /dev/null and b/docs/documentation/images/AvidaLogo.gif differ diff --git a/docs/documentation/images/Text_View_Env_Mode_1.jpg b/docs/documentation/images/Text_View_Env_Mode_1.jpg new file mode 100644 index 0000000..733e145 Binary files /dev/null and b/docs/documentation/images/Text_View_Env_Mode_1.jpg differ diff --git a/docs/documentation/images/Text_View_Env_Mode_2.jpg b/docs/documentation/images/Text_View_Env_Mode_2.jpg new file mode 100644 index 0000000..5447f8a Binary files /dev/null and b/docs/documentation/images/Text_View_Env_Mode_2.jpg differ diff --git a/docs/documentation/images/Text_View_Hist_Mode_1.jpg b/docs/documentation/images/Text_View_Hist_Mode_1.jpg new file mode 100644 index 0000000..a627159 Binary files /dev/null and b/docs/documentation/images/Text_View_Hist_Mode_1.jpg differ diff --git a/docs/documentation/images/Text_View_Hist_Mode_2.jpg b/docs/documentation/images/Text_View_Hist_Mode_2.jpg new file mode 100644 index 0000000..a3ef3d4 Binary files /dev/null and b/docs/documentation/images/Text_View_Hist_Mode_2.jpg differ diff --git a/docs/documentation/images/Text_View_Hist_Mode_3.jpg b/docs/documentation/images/Text_View_Hist_Mode_3.jpg new file mode 100644 index 0000000..b5eef6f Binary files /dev/null and b/docs/documentation/images/Text_View_Hist_Mode_3.jpg differ diff --git a/docs/documentation/images/Text_View_Map_Mode.jpg b/docs/documentation/images/Text_View_Map_Mode.jpg new file mode 100644 index 0000000..d57ac44 Binary files /dev/null and b/docs/documentation/images/Text_View_Map_Mode.jpg differ diff --git a/docs/documentation/images/Text_View_Navigation.jpg b/docs/documentation/images/Text_View_Navigation.jpg new file mode 100644 index 0000000..6433de1 Binary files /dev/null and b/docs/documentation/images/Text_View_Navigation.jpg differ diff --git a/docs/documentation/images/Text_View_Opt_Mode.jpg b/docs/documentation/images/Text_View_Opt_Mode.jpg new file mode 100644 index 0000000..3e2a70b Binary files /dev/null and b/docs/documentation/images/Text_View_Opt_Mode.jpg differ diff --git a/docs/documentation/images/Text_View_Stats_Mode.jpg b/docs/documentation/images/Text_View_Stats_Mode.jpg new file mode 100644 index 0000000..641ad9e Binary files /dev/null and b/docs/documentation/images/Text_View_Stats_Mode.jpg differ diff --git a/docs/documentation/images/Text_View_Zoom_Mode_1.jpg b/docs/documentation/images/Text_View_Zoom_Mode_1.jpg new file mode 100644 index 0000000..3133347 Binary files /dev/null and b/docs/documentation/images/Text_View_Zoom_Mode_1.jpg differ diff --git a/docs/documentation/images/Text_View_Zoom_Mode_2.jpg b/docs/documentation/images/Text_View_Zoom_Mode_2.jpg new file mode 100644 index 0000000..8c868cb Binary files /dev/null and b/docs/documentation/images/Text_View_Zoom_Mode_2.jpg differ diff --git a/docs/documentation/images/Text_View_Zoom_Mode_3.jpg b/docs/documentation/images/Text_View_Zoom_Mode_3.jpg new file mode 100644 index 0000000..9f3fe0b Binary files /dev/null and b/docs/documentation/images/Text_View_Zoom_Mode_3.jpg differ diff --git a/docs/documentation/images/cpu2.gif b/docs/documentation/images/cpu2.gif new file mode 100644 index 0000000..335514b Binary files /dev/null and b/docs/documentation/images/cpu2.gif differ diff --git a/docs/documentation/images/host-parasite-both-small.png b/docs/documentation/images/host-parasite-both-small.png new file mode 100644 index 0000000..8522b2d Binary files /dev/null and b/docs/documentation/images/host-parasite-both-small.png differ diff --git a/docs/documentation/images/inres_basic.gif b/docs/documentation/images/inres_basic.gif new file mode 100644 index 0000000..43d77aa Binary files /dev/null and b/docs/documentation/images/inres_basic.gif differ diff --git a/docs/documentation/images/inres_collect-specific.gif b/docs/documentation/images/inres_collect-specific.gif new file mode 100644 index 0000000..1994953 Binary files /dev/null and b/docs/documentation/images/inres_collect-specific.gif differ diff --git a/docs/documentation/images/inres_collect-unit-prob.gif b/docs/documentation/images/inres_collect-unit-prob.gif new file mode 100644 index 0000000..564039a Binary files /dev/null and b/docs/documentation/images/inres_collect-unit-prob.gif differ diff --git a/docs/documentation/images/inres_death.gif b/docs/documentation/images/inres_death.gif new file mode 100644 index 0000000..05e6a76 Binary files /dev/null and b/docs/documentation/images/inres_death.gif differ diff --git a/docs/documentation/images/inres_forcing.gif b/docs/documentation/images/inres_forcing.gif new file mode 100644 index 0000000..0f98a97 Binary files /dev/null and b/docs/documentation/images/inres_forcing.gif differ diff --git a/docs/documentation/images/inres_nop-collect.gif b/docs/documentation/images/inres_nop-collect.gif new file mode 100644 index 0000000..7ac38b2 Binary files /dev/null and b/docs/documentation/images/inres_nop-collect.gif differ diff --git a/docs/documentation/images/inres_specification.gif b/docs/documentation/images/inres_specification.gif new file mode 100644 index 0000000..24a8341 Binary files /dev/null and b/docs/documentation/images/inres_specification.gif differ diff --git a/docs/documentation/images/inres_split.gif b/docs/documentation/images/inres_split.gif new file mode 100644 index 0000000..0fcb51b Binary files /dev/null and b/docs/documentation/images/inres_split.gif differ diff --git a/docs/documentation/images/inres_using.gif b/docs/documentation/images/inres_using.gif new file mode 100644 index 0000000..9026e9a Binary files /dev/null and b/docs/documentation/images/inres_using.gif differ diff --git a/docs/workFlowTesting.rtf b/docs/workFlowTesting.rtf new file mode 100755 index 0000000..573e66f --- /dev/null +++ b/docs/workFlowTesting.rtf @@ -0,0 +1,144 @@ +Goals for 2017 0829 + + + +Avida + - Changes + - ./run_tests + - commit & push + +then +(automated tests) + + +Don’t have + - No method aside from commit msgs describing changes + - no unit tests + +Add in code commit lists + +or in the readme file? + +tagging commits with Av_ED 3.0.2 or what ever + - on both Avida and AV_UI so we know what version of Av_ui goes with which version of Avida Core + + + + +AV_UI + - changes + - haphazard tests by Diane by hand + - commit push + - get Jake to test + - fixes + - commit push with tag. + +_____________________________________________________________ +following Jake’s readme file on https://github.com/cousi2344/avida-ed-testing/blob/master/README.rst + +toward the end ran + python tests/test_suite_basic.py --setuipath . + +ExperimentControlsTest(BaseTest); + +Run the test longer and check to see that nothing bad happened + +pytest -v pathtotestfile/testfile.py + +all tests are in the test folder. Individual tests are in each of the following folders. +population +organism +analysis +Looking at one test + +pytest tests/common/common_basic/navigation/basic_nav_test.py +mac has forward slashes; +mac has back slashes; + +another example +pytest tests/population/population_basic/env_settings/pause_update_test.py +changed it to run for 19 instead of 9 updates. +β€”β€”β€”β€”β€” +Pull stuff to the av_ui folder within avida-ed-testing + + . venv/bin/activate +cd tests + + +_____________________________________________________________ +AV_UI change + +git clone on server +add in stand alone packages + +Test on Server + - automated tests + - tests done by hand + +Move Production to Archive (name with version number and date released) +Move test to β€œapp” folder + - Tag github at this time + +_____________________________________________________________ +Avida-ED change +pull av_ui changes +push changes +notify diane +tag when in production + +β€”β€”β€”β€”β€”β€”β€”β€”β€”β€” +wireframe fry +cartoon icons +some parts 2d and some parts 3d + +geneartive and proceedural things in games (Robin) +art assests, story, play through a book. + +Generative games + Mindcraft + No mans sky + small group of people generate a rich environment. + +Spore - not a good game + +box car d2 very simple looks crappy. + + + + +Fry + - how to swim at all + - evade predators + +Swim down stream. + +point sources of pollution + +Ocean +predators +gather food - grow + +Upstream + - fish ladders + - bears + +Mating + - finding a mate + - sexual selection + - + + +Robin + - much easier + - one kind of salmon + - swimming blobs + - keep the same blobs in all the environments + +add chemicals +speed of flow +increase the complexity of + +Box car 2d - has physics engine + + + \ No newline at end of file