Merge pull request #280 from EliasH-E/documenationClean

Made edits to Documentation for GenomeLibrary.h, HealthHosts.h, & SGPDataNodes.h

Author: anyaevostinar

source/sgp_mode/GenomeLibrary.h

@@ -59,6 +59,7 @@ class ProgramBuilder : emp::vector<sgpl::Instruction<Spec>> {
     push_back(inst);
   }
 
+
   sgpl::Program<Spec> Build(size_t length) {
     Add("Reproduce");
 
@@ -102,15 +103,6 @@ class ProgramBuilder : emp::vector<sgpl::Instruction<Spec>> {
     Add("SharedIO");
   }
 
-  void AddPrivateNot() {
-    // privateio   r0
-    // nand       r0, r0, r0
-    // privateio   r0
-    Add("PrivateIO");
-    Add("Nand");
-    Add("PrivateIO");
-  }
-
   void AddNand() {
     // sharedio   r0
     // sharedio   r1
@@ -122,17 +114,6 @@ class ProgramBuilder : emp::vector<sgpl::Instruction<Spec>> {
     Add("SharedIO");
   }
 
-  void AddPrivateNand() {
-    // sharedio   r0
-    // sharedio   r1
-    // nand       r0, r1, r0
-    // sharedio   r0
-    Add("PrivateIO");
-    Add("PrivateIO", 1);
-    Add("Nand", 0, 1, 0);
-    Add("PrivateIO");
-  }
-
   void AddAnd() {
     // ~(a nand b)
     // sharedio   r0
@@ -298,7 +279,8 @@ class ProgramBuilder : emp::vector<sgpl::Instruction<Spec>> {
      * Output: None.
      *
      * Purpose: Spread out donate instructions throughout the organism's genome in order to allow donations 
-     * during a symbiont's entire genome and not just in one place. Without the spread of instructions symbionts were unable to donate regularly.
+     * during a symbiont's entire genome and not just in one place. Without the spread of 
+     * instructions symbionts were unable to donate regularly.
      */
   void AddStartDonate(int donate_count){
 
@@ -319,17 +301,39 @@ class ProgramBuilder : emp::vector<sgpl::Instruction<Spec>> {
   }
 };
 
+
+/**
+ * Input: Total length of program
+ *
+ * Output: Program that contains only a Reproduce instruction
+ *
+ * Purpose: Used for testing reproduction
+ */
 sgpl::Program<Spec> CreateReproProgram(size_t length) {
   ProgramBuilder program;
   return program.Build(length);
 }
 
+/**
+ * Input: Total length of program
+ *
+ * Output: Program that performs a NOT operation
+ *
+ * Purpose: Creates the program for the majority of starting organisms
+ */
 sgpl::Program<Spec> CreateNotProgram(size_t length) {
   ProgramBuilder program;
   program.AddNot();
   return program.Build(length);
 }
 
+/**
+ * Input: Total length of program and the number of steal instructions that should be in the program
+ *
+ * Output: Program that performs a NOT operation and contains steal instructions
+ *
+ * Purpose: Creates a program for starting parasite symbionts when DONATION_STEAL_INST is enabled
+ */
 sgpl::Program<Spec> CreateParasiteNotProgram(size_t length, int steal_count) {
   ProgramBuilder program;
   if(steal_count < 0){
@@ -347,6 +351,14 @@ sgpl::Program<Spec> CreateParasiteNotProgram(size_t length, int steal_count) {
   return program.Build(length);
 }
 
+
+/**
+ * Input: Total length of program and the number of donate instructions that should be in the program
+ *
+ * Output: Program that performs a NOT operation and contains donate instructions
+ *
+ * Purpose: Creates a program for starting mutualist symbionts when DONATION_STEAL_INST is enabled
+ */
 sgpl::Program<Spec> CreateMutualistNotProgram(size_t length, int donate_count) {
   ProgramBuilder program;
   if(donate_count < 0){
@@ -363,6 +375,14 @@ sgpl::Program<Spec> CreateMutualistNotProgram(size_t length, int donate_count) {
   return program.Build(length);
 }
 
+
+/**
+ * Input: Total length of program
+ *
+ * Output: Program that performs the EQU operation
+ *
+ * Purpose: Creates a program that is able to perform EQU and reproduce, used for testing
+ */
 sgpl::Program<Spec> CreateEquProgram(size_t length) {
   ProgramBuilder program;
   program.AddEqu();
@@ -371,8 +391,11 @@ sgpl::Program<Spec> CreateEquProgram(size_t length) {
 
 
 /**
- * Picks what type of starting program should be created based on the config and
- * creates it.
+ * Input: A config file
+ *
+ * Output: Program for starting symbionts based on config
+ *
+ * Purpose: Assigns the correct program to the starting symbionts of the world
  */
 sgpl::Program<Spec> CreateStartProgram(emp::Ptr<SymConfigSGP> config) {
   if(config->DONATION_STEAL_INST() == 1){

source/sgp_mode/HealthHost.h

@@ -10,15 +10,13 @@ class HealthHost : public SGPHost {
     //Tracks whether an update needs to be given to a symbiont or received from a symbiont
     int cycles_given = 1;
 
-    //Test variables that are currently used to give symbionts some starting cycles and then give them scraps throughout
+    //Variables that are currently used to give symbionts some starting cycles and then give them scraps throughout
     //the rest of their updates.
     int honoray_cycles = 0;
     int starting_updates = 1;
     emp::Ptr<Organism> last_sym = NULL; 
       /**
-   * Constructs a new SGPHost as an ancestor organism, with either a random
-   * genome or a blank genome that knows how to do a simple task depending on
-   * the config setting RANDOM_ANCESTOR.
+   * Constructs a new SGPHost as an ancestor organism, with a blank genome that knows how to do a simple task.
    */
   HealthHost(emp::Ptr<emp::Random> _random, emp::Ptr<SGPWorld> _world,
           emp::Ptr<SymConfigSGP> _config, double _intval = 0.0,
@@ -92,7 +90,9 @@ class HealthHost : public SGPHost {
      * 
      * Output: None
      * 
-     * Purpose: TBD
+     * Purpose: To process the host, meaning: running its program code, which can
+     * include reproduction and acquisition of resources; removing dead syms;
+     * processing alive syms; Giving CPU cycles to syms; Receiving CPU cycles from syms;. 
      */
     void Process(emp::WorldPosition pos) override {
         if (GetDead()) {
@@ -116,8 +116,6 @@ class HealthHost : public SGPHost {
                 cycles_given = 0;
               }
 
-              
-              //cycles_given = 0;
             }
             if(cycles_given <= -1){
 
@@ -127,7 +125,7 @@ class HealthHost : public SGPHost {
                 sym_cycle += 1;
                 cycles_given = 0;
               }
-              //cycles_given = 0;
+              
 
             }
 
@@ -214,8 +212,8 @@ class HealthHost : public SGPHost {
                 curSym.Delete();
                 }
 
-        } // for each sym in syms
-        }   // if org has syms
+        } 
+        }   
 
       }
       GrowOlder();

source/sgp_mode/SGPDataNodes.h

@@ -31,8 +31,7 @@ void SGPWorld::CreateDataFiles() {
 
 
 /**
- * Input: The address of the string representing the file to be
- * created's name
+ * Input: A reference to the string that will be used as the files name
  *
  * Output: The address of the DataFile that has been created.
  *
@@ -56,6 +55,15 @@ emp::DataFile &SGPWorld::SetUpOrgCountFile(const std::string &filename) {
   return file;
 }
 
+/**
+ * Input: A reference to the string that will be used as the files name
+ *
+ * Output: The address of the DataFile that has been created.
+ *
+ * Purpose: To set up the file that will be used to track 
+ * task counts in the world.
+ * This includes the amount of each task completed for hosts and symbionts.
+ */
 emp::DataFile &SGPWorld::SetupTasksFile(const std::string &filename) {
   auto &file = SetupFile(filename);
   file.AddVar(update, "update", "Update");
@@ -73,7 +81,14 @@ emp::DataFile &SGPWorld::SetupTasksFile(const std::string &filename) {
   return file;
 }
 
-
+/**
+ * Input:A reference to the string that will be used as the files name
+ *
+ * Output: The address of the DataFile that has been created.
+ *
+ * Purpose: To set up the file that will be used to track 
+ * the amount of Donate and Steal instructions ran
+ */
 emp::DataFile &SGPWorld::SetupSymInstFile(const std::string &filename) {
   auto &file = SetupFile(filename);
   file.AddVar(update, "update", "Update");
@@ -109,8 +124,7 @@ void SGPWorld::SetupTransmissionFileColumns(emp::DataFile& file) {
 }
 
 /**
- * Input: The address of the string representing the file to be
- * created's name
+ * Input: A reference to the string that will be used as the files name
  *
  * Output: None
  *
@@ -183,8 +197,7 @@ void SGPWorld::WriteTaskCombinationsFile(const std::string& filename) {
 }
 
 /**
- * Input: The address of the string representing the file to be
- * created's name
+ * Input: A reference to the string that will be used as the files name
  *
  * Output: None
  *
@@ -229,7 +242,14 @@ void SGPWorld::WriteOrgReproHistFile(const std::string& filename) {
   out_file.close();
 }
 
-
+/**
+ * Input: None
+ *
+ * Output: None
+ *
+ * Purpose: To set up the data node storing the count 
+ * of each task completed for hosts and symbionts
+ */
 void SGPWorld::SetupTasksNodes() {
   if (!data_node_host_tasks.size()) {
     data_node_host_tasks.resize(task_set.NumTasks());
@@ -246,14 +266,27 @@ void SGPWorld::SetupTasksNodes() {
   }
 }
 
-
+/**
+ * Input: None
+ *
+ * Output: Data monitor for the number of steal instruction ran
+ *
+ * Purpose: Get Steal count data node and create it if it doesn't already exist
+ */
 emp::DataMonitor<int> &SGPWorld::GetStealCount() {
   if (!data_node_steal_count) {
     data_node_steal_count.New();
   }
   return *data_node_steal_count;
 }
 
+/**
+ * Input: None
+ *
+ * Output: Data monitor for the number of donate instruction ran
+ *
+ * Purpose: Get Donate count data node and create it if it doesn't already exist
+ */
 emp::DataMonitor<int> &SGPWorld::GetDonateCount() {
   if (!data_node_donate_count) {
     data_node_donate_count.New();

source/sgp_mode/SGPSymbiont.h

@@ -124,7 +124,14 @@ class SGPSymbiont : public Symbiont {
    */
   CPU &GetCPU() { return cpu; }
 
-
+  /**
+   * Input: Score of completed task, id of completed task
+   *
+   * Output: Calculated score to be received post interaction
+   *
+   * Purpose: Adjusts score that symbiont will receive based on whether it is giving some of its points to host
+   * or stealing some of the hosts points. 
+   */
   float DoTaskInteraction(float score, size_t task_id) {
     if(sgp_config->INTERACTION_MECHANISM() == 3){ //Nutrient mode
       emp::Ptr<SGPHost> host = my_host.DynamicCast<SGPHost>();

source/sgp_mode/Tasks.h

@@ -126,7 +126,7 @@ class TaskSet {
    *
    * Output: None
    *
-   * Purpose: Checks whether any tasks were completed and if so marks them as completing for reproductive purposes
+   * Purpose: Checks whether any tasks were completed and if so marks them as completed for reproductive purposes
    * and awards the proper amount of points.  
    */
   void ProcessOutput(CPUState &state, uint32_t output, bool is_only_task_credit){
@@ -240,6 +240,14 @@ class TaskSet {
 
   Iterator end() const { return Iterator{*this, tasks.size()}; }
 
+  /**
+   * Input: None
+   *
+   * Output: None
+   *
+   * Purpose: Resets the count of all tasks to 0 for both symbionts and hosts
+   * Used during the creation of the task data file and also for tests that check task counts
+   */
   void ResetTaskData() {
     for (size_t i = 0; i < tasks.size(); i++) {
       n_succeeds_host[i]->store(0);
@@ -252,6 +260,10 @@ class TaskSet {
  * The 9 default logic tasks in Avida
  * These are checked top-to-bottom and the reward is given for the first one
  * that matches
+ *
+ * Two of each logic task are stored, one where all tasks are worth 5 points
+ * and one where harder tasks are worth more points. 
+ * The SGP config DIFFERENT_TASK_VALUES enables differing points among tasks
 */
 const Task
     NOT = {"NOT", 1, 5.0, [](auto &x) { return ~x[0]; }},
@@ -273,13 +285,15 @@ const Task
     XOR_8 = {"XOR", 2,   8.0, [](auto &x) { return x[0] ^ x[1]; }},
     EQU_16 = {"EQU", 2,  16.0, [](auto &x) { return ~(x[0] ^ x[1]); }};
 
+//Set of tasks where all tasks are worth 5 points, used when DIFFERENT_TASK_VALUES is 0
 const TaskSet LogicTasks{
     emp::NewPtr<Task>(NOT), emp::NewPtr<Task>(NAND),
     emp::NewPtr<Task>(AND), emp::NewPtr<Task>(ORN),
     emp::NewPtr<Task>(OR),  emp::NewPtr<Task>(ANDN),
     emp::NewPtr<Task>(NOR), emp::NewPtr<Task>(XOR),
     emp::NewPtr<Task>(EQU)};
 
+//Set of tasks where harder tasks are worth more points, used when DIFFERENT_TASK_VALUES is 1
 const TaskSet LogicTasksDiff{
   emp::NewPtr<Task>(NOT_1), emp::NewPtr<Task>(NAND_1),
   emp::NewPtr<Task>(AND_2), emp::NewPtr<Task>(ORN_2),