Documentation

A documentation section has been created using Read The Docs and is found in "/doc/RTD". In order to create the documentation Sphinx v1.3.1 was used. To create the html file use:

make html

which creates "index.html" in "_build/html/".

An initial design layout has been created and initial drafts of the Task-Based Parallelism and Hierarchical Cell Decomposition have been completed and need inclusion in the master branch.

doc/RTD/DeveloperGuide/AddingTasks/addingtasks.rst

+.. _NewTask:
+
+How to add a new task to SWIFT?
+=================================
+.. highlight:: c
+
+
+
+.. toctree::
+   :maxdepth: 0
+
+This tutorial will step through how to add a new task to swift. First we will go through the 
+idealology of adding a new task to SWIFT. This will be followed by an example of how to add a task
+for an imposed external gravitational field to SWIFT and a task to include "cooling" to the gas particles.
+
+In the simplest case adding a new tasks requires changes to five files, namely:
+
+* task.h
+* cell.h
+* timers.h
+* task.c
+* engine.c
+
+Further, implementation details of what the task will then do should be added to another file
+(for example runner_myviptask.c) which will contain the actual task implementation.
+
+So now lets look at what needs to change in each of the files above, starting with task.h
+
+--------------
+**task.h**
+--------------
+Within task.h there exists a structure of the form:: 
+
+    /* The different task types. */
+    enum task_types {
+        task_type_none = 0,
+        task_type_sort,
+        task_type_self,
+        task_type_pair,
+	      .
+	      .
+	      .
+	task_type_my_new_task,
+	task_type_psort,
+	task_type_split_cell,
+	task_type_count
+    };
+
+Within this task structure your new task should be added. Add the task entry anywhere in the struct before the
+task_type_count member. This last entry is used to count the number of tasks and must always be the last entry.
+
+--------------
+**task.c**
+--------------
+
+Within task.c the addition of the new task type must be include in a character list (which at the moment is only 
+used for debugging purposes)::
+
+     /* Task type names. */
+     const char *taskID_names[task_type_count] = {
+     "none",  "sort",    "self",    "pair",    "sub",
+     "ghost", "kick1",   "kick2",   "send",    "recv",
+     "link",  "grav_pp", "grav_mm", "grav_up", "grav_down",
+     "my_new_task", "psort", "split_cell"};
+
+The new task type should be added to this list in the same order as it was added within the task_types struct in 
+task.h
+
+--------------
+**cell.h**
+--------------
+
+cell.h contains pointers to all of the tasks associated with that cell. You must include your new task type 
+here e.g::
+
+   struct task *my_new_task;
+
+--------------
+**timers.h**
+--------------
+
+Within timers.h is an enumerated list of timers associated with each task. The timers measure the time required 
+to execute a given task and this information is used in improve scheduling the task in future iterations::
+
+    /* The timers themselves. */
+    enum {
+      timer_none = 0,
+      timer_prepare,
+      timer_kick1,
+           .
+	   .
+	   .
+      timer_new_task,
+      timer_step,
+      timer_count,
+    };
+
+--------------
+**engine.c**
+--------------
+
+Finally, in engine.c the new task is added so that the scheduler knows to include the task in the list of tasks 
+to be scheduled. Knowing where to add the task in engine.c is a little bit more difficult. This will depend on 
+the type of task involved and whether it is a task that acts only on a individual particle independent of other 
+particles (e.g. a cooling a task) or whether the task depends on other tasks (e.g. density, force or feedback). 
+
+If we assume that the task is a particle only task then the first place to modify is the engine_mkghosts() 
+function. Within this function the new task must be added to the list of tasks 
+(within the c->nodeID == e->nodeID if clause)::
+
+       /* Generate the external gravity task*/
+         c->my_new_task = scheduler_addtask(s, task_type_my_new_task, task_subtype_none, 0, 0,
+                                   c, NULL, 0);
+
+
+That's pretty much it - but what about dependencies and conflicts?
+Remember SWIFT automatically handles conflicts (by understanding which tasks need to write to the same data) so 
+you (the developer) don't need to worry about conflicts. Dependencies do however need to be managed and they will
+be task specific. The following two examples, implementing cooling and an imposed external gravitational field
+will illustrate how dependencies should be treated. 
+
+
+Examples:
+
+:ref:`ExternalGravityExample`
+
+:ref:`CoolingExample`