.. _output-scheduler:

****************
Output Scheduler
****************

In an analysis with multiple regions, it can be difficult to synchronize output such as results files, history files, and restart files. To help synchronize output for analyses with multiple regions, an ``OUTPUT SCHEDULER`` command block may be defined at the SIERRA scope. This scheduler can then be referenced

- in the ``RESULTS OUTPUT`` command block to control the output of results information,
- in the ``HISTORY OUTPUT`` command block to control the output of history information,
- in the ``HEARTBEAT OUTPUT`` command block to control the output of heartbeat information, and/or
- in the ``RESTART DATA`` command block to control the writing of restart files.

The ``OUTPUT SCHEDULER`` command block is defined in the SIERRA scope and is referenced by a ``USE OUTPUT SCHEDULER`` command line inside the appropriate output block. :numref:`output-schedulerblock` describes the ``OUTPUT SCHEDULER`` command block, and :numref:`output-examscheduler` illustrates how this block is referenced with the ``USE OUTPUT SCHEDULER`` command line.

.. _output-schedulerblock:

Output Scheduler Command Block
==============================

.. parsed-literal::

   BEGIN OUTPUT SCHEDULER <string>scheduler_name
     START TIME = <real>output_start_time
     TIMESTEP ADJUSTMENT INTERVAL = <integer>steps |explicit_mini|
     AT TIME <real>time_begin INCREMENT =
       <real>time_increment_dt
     ADDITIONAL TIMES = <real>output_time1
       <real>output_time2 ...
     AT STEP <integer>step_begin INCREMENT =
       <integer>step_increment
     ADDITIONAL STEPS = <integer>output_step1
       <integer>output_step2 ...
     TERMINATION TIME = <real>termination_time_value
   END [OUTPUT SCHEDULER <string>scheduler_name]

An output scheduler is defined with a command block in the SIERRA scope. The ``OUTPUT SCHEDULER`` command block begins with the input line:

.. code-block:: sierrainput

   BEGIN OUTPUT SCHEDULER <string>scheduler_name

and is terminated with the line:

.. code-block:: sierrainput

   END OUTPUT SCHEDULER <string>scheduler_name

where ``scheduler_name`` is a user-defined name for the command block. All the normal scheduling command lines are valid in an ``OUTPUT SCHEDULER`` command block.

Specifying Time Steps for Output
--------------------------------

The same output step control commands available for results output are also available in the output scheduler. See :numref:`output-results-exodus-timesteps`.

.. _output-examscheduler:

Example of Using the Output Scheduler
=====================================

Once an output scheduler has been defined via the ``OUTPUT SCHEDULER`` command block, it can be used by inserting a ``USE OUTPUT SCHEDULER`` command line in any of the command blocks: ``RESULTS OUTPUT``, ``HISTORY OUTPUT``, and ``RESTART DATA``. The next paragraph provides an example of using output schedulers.

In the SIERRA scope, we define two output schedulers, ``Timer`` and ``Every_Step``:

.. code-block:: sierrainput

   BEGIN OUTPUT SCHEDULER Timer
     AT TIME 0.0 INCREMENT = 10.0e-6
     TIME STEP ADJUSTMENT INTERVAL = 4
   END OUTPUT SCHEDULER Timer
   #
   BEGIN OUTPUT SCHEDULER Every_Step
     AT STEP 0 INCREMENT = 1
   END OUTPUT SCHEDULER Every_Step

With the ``USE OUTPUT SCHEDULER`` command, we reference the scheduler named ``Timer`` for results output:

.. code-block:: sierrainput

   BEGIN RESULTS OUTPUT Out_Region_1
     .
     USE OUTPUT SCHEDULER Timer
     .
   END RESULTS OUTPUT Out_Region_1

With the ``USE OUTPUT SCHEDULER`` command, we reference the scheduler named ``Every_STEP`` for history output:

.. code-block:: sierrainput

   BEGIN HISTORY OUTPUT Out_Region_2
     .
     USE OUTPUT SCHEDULER Every_Step
     .
   END HISTORY OUTPUT Out_Region_2
