diff --git a/doc/RTD/DeveloperGuide/AddingTasks/index.rst b/doc/RTD/DeveloperGuide/AddingTasks/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..9bf5321d16c46574f800e211b599eb9ccfc303b0 --- /dev/null +++ b/doc/RTD/DeveloperGuide/AddingTasks/index.rst @@ -0,0 +1,97 @@ +.. _GettingStarted: + +How to add a new task to SWIFT? +================================= +.. highlight:: c + +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. + +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 + +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. + +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 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 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:: + + /* The timers themselves. */ + enum { + timer_none = 0, + timer_prepare, + timer_kick1, + . + . + . + timer_new_task, + timer_step, + timer_count, + }; + +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: +.. toctree:: + :maxdepth: 0 + diff --git a/doc/RTD/DeveloperGuide/index.rst b/doc/RTD/DeveloperGuide/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..008213ed383e89413c56f316ac5a298b6db8b1b6 --- /dev/null +++ b/doc/RTD/DeveloperGuide/index.rst @@ -0,0 +1,10 @@ +.. _GettingStarted: + +A Developer Guide for SWIFT +================================= + + +.. toctree:: + :maxdepth: 1 + + AddingTasks/index.rst diff --git a/doc/RTD/index.rst b/doc/RTD/index.rst index 2fc11ea6337654c509b77032ffba2c79289868d2..129797af6abd764764549b64b3cc3a546dafa015 100644 --- a/doc/RTD/index.rst +++ b/doc/RTD/index.rst @@ -17,6 +17,7 @@ Contents: Motivation/index.rst Innovation/index.rst Physics/index.rst + DeveloperGuide/index.rst FAQ/index.rst Indices and tables