diff --git a/doc/RTD/DeveloperGuide/AddingTasks/index.rst b/doc/RTD/DeveloperGuide/AddingTasks/addingtasks.rst
similarity index 79%
rename from doc/RTD/DeveloperGuide/AddingTasks/index.rst
rename to doc/RTD/DeveloperGuide/AddingTasks/addingtasks.rst
index 9bf5321d16c46574f800e211b599eb9ccfc303b0..936fc5b45f901cbb704545727dac1211ac58b5a4 100644
--- a/doc/RTD/DeveloperGuide/AddingTasks/index.rst
+++ b/doc/RTD/DeveloperGuide/AddingTasks/addingtasks.rst
@@ -1,12 +1,17 @@
-.. _GettingStarted:
+.. _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 for an example of how to add a task
-for an imposed external gravitational field to SWIFT.
+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:
@@ -21,6 +26,9 @@ Further, implementation details of what the task will then do should be added to
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. */
@@ -41,7 +49,12 @@ Within task.h there exists a structure of the form::
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.
-With 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.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] = {
@@ -50,13 +63,24 @@ With task.c the addition of the new task type must be include in a character lis
"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
+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::
+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;
-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::
+--------------
+**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 {
@@ -71,6 +95,10 @@ Within timers.h is an enumerated list of timers associated with each task. The t
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
@@ -91,7 +119,9 @@ you (the developer) don't need to worry about conflicts. Dependencies do however
be task specific. The following two examples, implementing cooling and an imposed external gravitational field
will illustrate how dependencies should be treated.
+
Examples:
-.. toctree::
- :maxdepth: 0
+:ref:`ExternalGravityExample`
+
+:ref:`CoolingExample`
diff --git a/doc/RTD/DeveloperGuide/Examples/Cooling/cooling.rst b/doc/RTD/DeveloperGuide/Examples/Cooling/cooling.rst
new file mode 100644
index 0000000000000000000000000000000000000000..5dc0c46a1881601115ceee1b2ac5b205e2fb1e5b
--- /dev/null
+++ b/doc/RTD/DeveloperGuide/Examples/Cooling/cooling.rst
@@ -0,0 +1,11 @@
+.. _CoolingExample:
+
+Cooling Example
+--------------------------
+
+An example of how to implement a particle cooling task in SWIFT
+===================================================================
+
+
+.. toctree::
+ :maxdepth: 1
diff --git a/doc/RTD/DeveloperGuide/Examples/ExternalGravity/externalgravity.rst b/doc/RTD/DeveloperGuide/Examples/ExternalGravity/externalgravity.rst
new file mode 100644
index 0000000000000000000000000000000000000000..aceba80bb96dc69d942cbc675669c49fc7f2cf13
--- /dev/null
+++ b/doc/RTD/DeveloperGuide/Examples/ExternalGravity/externalgravity.rst
@@ -0,0 +1,225 @@
+.. _ExternalGravityExample:
+
+External Gravity Task Example
+----------------------------------
+
+An example of how to implement an external gravity task in SWIFT
+=====================================================================
+
+An external gravitational field can be imposed in SWIFT to mimic self-gravity. This is done by assigning
+a gravitational force that falls as $1/ r^2$ (mathjax support to be included).
+
+In order to do this we update the files as described in :ref:`NewTask`. For the specific case of adding an
+external graviational field the additions are as follows:
+
+
+--------------
+**task.h**
+--------------
+
+Code (snapshot Nov 2015)::
+
+ /* The different task types. */
+ enum task_types {
+ task_type_none = 0,
+ task_type_sort,
+ task_type_self,
+ task_type_pair,
+ task_type_sub,
+ task_type_ghost,
+ task_type_kick1,
+ task_type_kick2,
+ task_type_send,
+ task_type_recv,
+ task_type_link,
+ task_type_grav_pp,
+ task_type_grav_mm,
+ task_type_grav_up,
+ task_type_grav_down,
+ **task_type_grav_external,**
+ task_type_psort,
+ task_type_split_cell,
+ task_type_count
+ };
+
+Task of type - task_type_grav_external - added to list of tasks.
+
+--------------
+**task.c**
+--------------
+
+Code (snapshot Nov 2015)::
+
+ /* 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", "grav_external",
+ "psort", "split_cell"
+ };
+
+Task added to list of task names (used only for debugging purposed).
+
+
+--------------
+**cell.h**
+--------------
+
+Code (snapshot Nov 2015)::
+
+ /* The ghost task to link density to interactions. */
+ struct task *ghost, *kick1, *kick2, *grav_external;
+
+Struture of type "task" declared (or pointer to a task at least).
+
+
+
+--------------
+**timers.h**
+--------------
+
+Code (snapshot Nov 2015)::
+
+ /* The timers themselves. */
+ enum {
+ timer_none = 0,
+ timer_prepare,
+ timer_kick1,
+ timer_kick2,
+ timer_dosort,
+ timer_doself_density,
+ timer_doself_force,
+ timer_doself_grav,
+ timer_dopair_density,
+ timer_dopair_force,
+ timer_dopair_grav,
+ timer_dosub_density,
+ timer_dosub_force,
+ timer_dosub_grav,
+ timer_dopair_subset,
+ timer_doghost,
+ timer_dograv_external,
+ timer_gettask,
+ timer_qget,
+ timer_qsteal,
+ timer_runners,
+ timer_step,
+ timer_count,
+ };
+
+The timer list is updated to include a timer task.
+
+
+--------------
+**engine.c**
+--------------
+
+Code (snapshot Nov 2015)::
+
+ void engine_mkghosts(struct engine *e, struct cell *c, struct cell *super) {
+
+ int k;
+ struct scheduler *s = &e->sched;
+
+ /* Am I the super-cell? */
+ if (super == NULL && c->nr_tasks > 0) {
+
+ /* Remember me. */
+ super = c;
+
+ /* Local tasks only... */
+ if (c->nodeID == e->nodeID) {
+
+ /* Generate the external gravity task*/
+ c->grav_external = scheduler_addtask(s, task_type_grav_external, task_subtype_none, 0, 0,
+ c, NULL, 0);
+
+ /* Enforce gravity calculated before kick 2 */
+ scheduler_addunlock(s, c->grav_external, c->kick2);
+ }
+ }
+ }
+
+
+The first function call adds the task to the scheduler. The second function call takes care of the dependency
+involved in imposing an external gravitational field. These two functions are worth considering due to their
+obvious importance.
+
+
+
+The function prototype for the addtask function is (**found in scheduler.c**)::
+
+ struct task *scheduler_addtask(struct scheduler *s, int type, int subtype,
+ int flags, int wait, struct cell *ci,
+ struct cell *cj, int tight) {
+
+This function adds a task to the scheduler. In the call to this function in engine.c we used the actual
+parameters **s** for the scheduler, **task_type_grav_external** for the (task) type, task_subtype_none for
+the (task) subtype, zeros for the flags and wait parameters, **c** for the pointer to our cell, NULL for the
+cell we interact with since there is none and 0 for the tight parameter.
+
+The function prototype for the addunlock function is(**found in scheduler.c**)::
+
+ void scheduler_addunlock(struct scheduler *s, struct task *ta,
+ struct task *tb) {
+
+This function signals when the unlock a certain task. In our case we use the external gravity task to unlock the
+kick2 task - i.e. kick2 depends on external gravity. So when calling the addunlock function the
+order is the **ta** task should be the task to unlock and **tb** should the task that does the unlocking.
+
+
+--------------
+**runner.c**
+--------------
+
+In runner.c the implementation of the external gravity task is taken care of. The function prototype is::
+
+ void runner_dograv_external(struct runner *r, struct cell *c) {
+
+The function takes a pointer to a runner struct and a pointer to the cell struct. The entire function call is::
+
+
+
+ void runner_dograv_external(struct runner *r, struct cell *c) {
+
+ struct part *p, *parts = c->parts;
+ float rinv;
+ int i, ic, k, count = c->count;
+ float dt_step = r->e->dt_step;
+ TIMER_TIC
+
+ /* Recurse? */
+ if (c->split) {
+ for (k = 0; k < 8; k++)
+ if (c->progeny[k] != NULL) runner_dograv_external(r, c->progeny[k]);
+ return;
+ }
+
+ /* Loop over the parts in this cell. */
+ for (i = 0; i < count; i++) {
+
+ /* Get a direct pointer on the part. */
+ p = &parts[i];
+
+ /* Is this part within the time step? */
+ if (p->dt <= dt_step) {
+ rinv = 1 / sqrtf((p->x[0])*(p->x[0]) + (p->x[1])*(p->x[1]) + (p->x[2])*(p->x[2]));
+ for(ic=0;ic<3;ic++){
+ p->grav_accel[ic] = - const_G * (p->x[ic]) * rinv * rinv * rinv;
+ }
+ }
+ }
+ TIMER_TOC(timer_dograv_external);
+ }
+
+
+The key component of this function is the calculation of **rinv** and then the imposition of the
+**grav_accel** to this particle. **rinv** is calculated assuming the centre of the gravitational
+potential lies at the origin. The acceleration of each particle then is calculated by multiplying
+the graviational constant by the component of the position along one axis divided by R^3. The
+gravitational acceleration is then added to the total particle acceleration **a**.
+
+
+
+.. toctree::
+ :maxdepth: 1
diff --git a/doc/RTD/DeveloperGuide/developerguide.rst b/doc/RTD/DeveloperGuide/developerguide.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0c2cbe23c681af2dc4302b74e3c8c9f44fce5bef
--- /dev/null
+++ b/doc/RTD/DeveloperGuide/developerguide.rst
@@ -0,0 +1,13 @@
+.. _DeveloperGuide:
+
+A Developer Guide for SWIFT
+=================================
+
+
+.. toctree::
+ :maxdepth: 1
+
+ AddingTasks/addingtasks.rst
+ Examples/ExternalGravity/externalgravity.rst
+ Examples/Cooling/cooling.rst
+
diff --git a/doc/RTD/DeveloperGuide/index.rst b/doc/RTD/DeveloperGuide/index.rst
deleted file mode 100644
index 008213ed383e89413c56f316ac5a298b6db8b1b6..0000000000000000000000000000000000000000
--- a/doc/RTD/DeveloperGuide/index.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-.. _GettingStarted:
-
-A Developer Guide for SWIFT
-=================================
-
-
-.. toctree::
- :maxdepth: 1
-
- AddingTasks/index.rst
diff --git a/doc/RTD/Physics/Gravity/index.rst b/doc/RTD/Physics/Gravity/gravity.rst
similarity index 94%
rename from doc/RTD/Physics/Gravity/index.rst
rename to doc/RTD/Physics/Gravity/gravity.rst
index 47f74ab44cccc073016f74b0112ffd91433df5df..82b60bc01747f1693ff2d99fc09db8a5e23d7043 100644
--- a/doc/RTD/Physics/Gravity/index.rst
+++ b/doc/RTD/Physics/Gravity/gravity.rst
@@ -1,4 +1,4 @@
-.. _gravity:
+.. _SWIFTGravity:
Gravity
=============================
@@ -6,5 +6,6 @@ Gravity
SWIFT implements the calculation of gravitational forces using a version of TreePM.
Matthieu - can you update this part? I know you have implemented a Multipole method here
with some SWIFT specific modifications. Could you write a brief overview of the idea?
+
.. toctree::
:maxdepth: 1
diff --git a/doc/RTD/Physics/SPH/index.rst b/doc/RTD/Physics/SPH/sph.rst
similarity index 87%
rename from doc/RTD/Physics/SPH/index.rst
rename to doc/RTD/Physics/SPH/sph.rst
index c211ab8378772b5314fcc4d8d4a6edbfc0705fc9..feadec4bcd48a161c80bc4ecf09345278e20ab87 100644
--- a/doc/RTD/Physics/SPH/index.rst
+++ b/doc/RTD/Physics/SPH/sph.rst
@@ -1,4 +1,4 @@
-.. _GettingStarted:
+.. _SWIFTSPH:
Smooth Particle Hydrodynamics
=============================
diff --git a/doc/RTD/Physics/index.rst b/doc/RTD/Physics/index.rst
index fcd06336e1e1768610452be5f7dae66d3b9f490d..536c135ec47d83791ba50dd55246f4c6a9559e9e 100644
--- a/doc/RTD/Physics/index.rst
+++ b/doc/RTD/Physics/index.rst
@@ -1,4 +1,4 @@
-.. _GettingStarted:
+.. _SWIFTPhysics:
What Physics does SWIFT Simulate?
=================================
@@ -7,4 +7,5 @@ What Physics does SWIFT Simulate?
.. toctree::
:maxdepth: 1
- SPH/index.rst
+ SPH/sph.rst
+ Gravity/gravity.rst
diff --git a/doc/RTD/conf.py b/doc/RTD/conf.py
index aaf11c890627203928344ea0b7a6ca4681c482d4..b4eab3d354322f8ff5e060b1795c2654eb879f90 100644
--- a/doc/RTD/conf.py
+++ b/doc/RTD/conf.py
@@ -41,7 +41,7 @@ master_doc = 'index'
# General information about the project.
project = u'SWIFT'
-copyright = u'2015, John Regan, James Willis, Stefan Arridge, Matthieu Schaller'
+copyright = u'2015: John Regan, James Willis, Stefan Arridge, Matthieu Schaller'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
diff --git a/doc/RTD/index.rst b/doc/RTD/index.rst
index 129797af6abd764764549b64b3cc3a546dafa015..1d2b08ceb8e227ba9fee306ab26ae9a490308dc4 100644
--- a/doc/RTD/index.rst
+++ b/doc/RTD/index.rst
@@ -17,7 +17,7 @@ Contents:
Motivation/index.rst
Innovation/index.rst
Physics/index.rst
- DeveloperGuide/index.rst
+ DeveloperGuide/developerguide.rst
FAQ/index.rst
Indices and tables