<commit_before>.._measure_edition:

Measure edition
===============

So far this guide has only covered the basic edition of the tasks using the
tree view of the hierarchy and the standard editor. The following sections will
go further and explain how other editors can allow to fine tune the measure and
how to use the tools that are pre/post-execution hooks and the monitors.

.. contents::

.. measure_edition_editors:

Advanced use of editors
-----------------------

Dependending on the currently selected task, different editors can be
available :

- the standard editor used to edit the tasks is always present.
- the execution editor is also always present.
- the task database access editor is present for the tasks that can have
  children tasks.
- other editors contributed by plugins may be present for some tasks.

The standard editor provide a different view for each task depending on its
parameters and is hence the most commonly used.
For example, if you create a "Definition" task, it will appear in the standard
editor, first as a "Add first element" button, and then once you click on it
as two blank writing fields where you can enter a name and its definition.
A chevron button allows you to add another definition below.

The execution and database access editors present similar graphical user
interface for all tasks and are used to set common settings that would make
the standard editor unusable if they were present on it. They are available as
additional tabs above the tasks view. Their use is detailed in the next
sections.

Execution editor
^^^^^^^^^^^^^^^^

The execution editor as its name states can be used to edit the way a task will
be executed. Three parameters are editable :

- can the application be stopped/paused just before executing a task ? By
  default this is the case for all the tasks and has only a very limited
  overhead. This is controlled by the 'Stoppable' checkbox.
- should the task be executed in a new thread ? This setting controlled by the
  'Parallel' checkbox can be misleading in that in Python only one thread can
  execute python code at any time. However this constrained is released when
  calling C code (typically when performing IO operations such as writing into
  a file or communicating with an instrument). So if your experiment needs to
  set multiple instruments states before performing a measure you may gain
  time by doing the settings 'in parallel'. When executing a task in parallel
  it should be associated with a pool. A pool is nothing else than an id that
  will be used for synchronisation.
- should the task wait for any other task before running ? This is the pendant
  of the parallel setting: if a task is executed in parallel it may be crucial
  for another task to be sure that it has completed before running. This
  setting is controlled by the 'Wait' checkbox. When checked you can choose on
  which parallel pool to wait on (hence the id), or not to wait on some pools
  or to wait on all pools.

.. note::<commit_msg>docs: Added documentation for the instrument pools<commit_after>.._measure_edition:

Measure edition
===============

So far this guide has only covered the basic edition of the tasks using the
tree view of the hierarchy and the standard editor. The following sections will
go further and explain how other editors can allow to fine tune the measure and
how to use the tools that are pre/post-execution hooks and the monitors.

.. contents::

.. measure_edition_editors:

Advanced use of editors
-----------------------

Dependending on the currently selected task, different editors can be
available :

- the standard editor used to edit the tasks is always present.
- the execution editor is also always present.
- the task database access editor is present for the tasks that can have
  children tasks.
- other editors contributed by plugins may be present for some tasks.

The standard editor provide a different view for each task depending on its
parameters and is hence the most commonly used.
For example, if you create a "Definition" task, it will appear in the standard
editor, first as a "Add first element" button, and then once you click on it
as two blank writing fields where you can enter a name and its definition.
A chevron button allows you to add another definition below.

The execution and database access editors present similar graphical user
interface for all tasks and are used to set common settings that would make
the standard editor unusable if they were present on it. They are available as
additional tabs above the tasks view. Their use is detailed in the next
sections.

Execution editor
^^^^^^^^^^^^^^^^

The execution editor as its name states can be used to edit the way a task will
be executed. Three parameters are editable :

- can the application be stopped/paused just before executing a task ? By
  default this is the case for all the tasks and has only a very limited
  overhead. This is controlled by the 'Stoppable' checkbox.
- should the task be executed in a new thread ? This setting controlled by the
  'Parallel' checkbox can be misleading in that in Python only one thread can
  execute python code at any time. However this constrained is released when
  calling C code (typically when performing IO operations such as writing into
  a file or communicating with an instrument). So if your experiment needs to
  set multiple instruments states before performing a measure you may gain
  time by doing the settings 'in parallel'. When executing a task in parallel
  it should be associated with a pool. A pool is nothing else than an id that
  will be used for synchronisation.
- should the task wait for any other task before running ? This is the pendant
  of the parallel setting: if a task is executed in parallel it may be crucial
  for another task to be sure that it has completed before running. This
  setting is controlled by the 'Wait' checkbox. When checked you can choose on
  which parallel pool to wait on (hence the id), or not to wait on some pools
  or to wait on all pools.

Task pools
""""""""""

A pool simply consist in a user-defined group of tasks.
In a measure, each task can be associated with a pool from the dropdown menu
of the execution editor. To define a new pool, right click on the menu and
enter a name. You will then be able to select one or multiple of you defined
pool(s) in the wait or no wait options.

.. note::
{'fraction_non_alphanumeric': 0.04420921544209216, 'fraction_numerical': 0.0, 'mean_word_length': 3.8859315589353614, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2546506', 'n_tokens_mistral': 1498, 'n_tokens_neox': 1450, 'n_words': 1053}