.. _inputs_subvolume:
  
Section: Subvolume
~~~~~~~~~~~~~~~~~~

This section controls subvolume post-processing. Subvolume outputs chunks
of data directly from the computational mesh.
The prefix is the label set in ``incflo.post_processing``. For example
``incflo.post_processing = subvol1``


.. input_param:: subvol1.type

   **type:** String, mandatory

   To use subvolume post-processing, specify with keyword ``Subvolume``

.. input_param:: subvol1.labels

   **type:** List of strings, mandatory

   Similar to the Sampling utility, multiple subvolumes can be defined within a
   single Subvolume instance, where the top-level label is used to define the fields
   and output parameters and the bottom-level labels are used to define the type
   of subvolume and its spatial parameters. Below, the label ``chunk1`` will be used
   where applicable.

.. input_param:: subvol1.fields

   **type:** List of strings, mandatory

   Specify which field arrays should be output within the selected subvolume 

.. input_param:: subvol1.int_fields

   **type:** List of strings, optional, default is empty

   Specify which integer field arrays should be output within the selected subvolume

.. input_param:: subvol1.derived_fields

   **type:** List of strings, optional, default is empty

   Specify which derived field arrays should be output within the selected subvolume (e.g. mag_vorticity, mask_terrain(velocity)). 

   The ``mask_terrain(<field>)`` derived field copies ``<field>`` and overwrites
   every cell inside the terrain body (where ``terrain_blank == 1``) with ``NaN``,
   producing a plot variable named ``<field>_masked``. For example,
   ``mask_terrain(velocity)`` outputs ``velocity_masked``. It requires the
   ``terrain_blank`` int field, which is provided by physics modules such as
   ``TerrainDrag`` or ``ChannelBuilder``. The subvolume output copies derived
   values directly into the output (no interpolation), so the ``NaN`` cells are
   written to the plotfile unchanged.

.. input_param:: subvol1.output_rename

   **type:** String, optional

   If desired, use a different name for the top-level label when writing. In this example,
   this would replace the ``subvol1`` label in the naming of the output directories. This
   option is primarily intended to enable different subvolumes to have the same top-level
   names despite needing different top-level parameters. In that case, it is the responsibility
   of the user to ensure the bottom-level names are still different, as this is not checked by the code.

.. input_param:: subvol1.chunk1.type

   **type:** String, optional, default = Rectangular

   This specifies the type of subvolume to be used. At the moment, Rectangular is the only available type.
   Rectangular subvolumes are defined using an origin, number of cells, and cell size.

.. input_param:: subvol1.chunk1.origin

   **type:** Vector<Real>, mandatory

   Starting point in three-dimensional space to define the rectangular subvolume. This needs
   to be the lower left corner of a mesh cell for the subvolume data extraction to work properly.
   This always corresponds to the source mesh level cell corners, even if the output cell size is
   coarser than the source level.

.. input_param:: subvol1.chunk1.num_points

   **type:** Vector<Int>, mandatory

   Number of points (more accurately, cells) in each direction to include in the rectangular subvolume.

.. input_param:: subvol1.chunk1.dx_vec

   **type:** Vector<Real>, mandatory

   Output cell size, in each direction, for the rectangular subvolume. The spacing can be anisotropic and
   does not need to match a mesh level exactly. Instead, each entry must be an integer multiple of the source
   level cell size in that direction, so sampled values still come directly from source cell centers.
   This allows outputs that are coarser than the base level. If a single cell size is specified through
   the :input_param:`subvol1.chunk1.dx` argument below, then this argument (:input_param:`subvol1.chunk1.dx_vec`) is not required.

.. input_param:: subvol1.chunk1.dx

   **type:** Real, optional

   Cell size for the rectangular subvolume. This optional argument can be used in place of
   :input_param:`subvol1.chunk1.dx_vec` to specify a single (isotropic) output cell size.
   As with ``dx_vec``, the value must map to an integer multiple of the selected source level spacing.

.. input_param:: subvol1.chunk1.chunk_size_vec

   **type:** Vector<Int>, optional

   Optional argument for more control over how the data is partitioned within a subvolume. By default,
   the chunk size will be the max grid size in each spatial direction.