:orphan:

.. index:: read_grid

.. _read-grid:

.. _read-grid-command:

#################
read_grid command
#################

.. _read-grid-syntax:

*******
Syntax:
*******

::

   read_grid filename keyword args ...

- filename = name of grid file 

- zero or more keyword/args pairs may be appended

- keyword = *custom*

::

     *custom* args = name datatype Nc
       name = name of custom per-grid vector or array
       datatype = *int* or *float* = for integer or floating point values
       Nc = 0 for a vector (single value), Nc >= 1 for an array (one or more values)

.. _read-grid-examples:

*********
Examples:
*********

::

   read_grid data.grid
   read_grid data.grid custom temperature double 0

.. _read-grid-descriptio:

************
Description:
************

Read a grid file in text format which lists the grid cell IDs to be
used to construct a hierarchical grid that overalys the simulation
domain defined by the :ref:`create_box<create-box>` command.  The grid
can also be defined by the :ref:`create_grid<create-grid>` command.

.. note::

  that if the grid is hierarchical, grid cell IDs are not
  simply numbered from 1 to N.  They also encode the cell's logical
  position within the grid hierarchy.

The specified file can be a text file or a gzipped text file (detected
by a .gz suffix).  See the :ref:`write_grid<writegrid>` command for a
description of the format of the file.

The grid cell IDs read from the file (one per line) are assigned to
processors in a round-robin fashion, which means in general the set of
cells a processor owns will not be contiguous in a geometric sense.
They are thus assumed to be a "dispersed" assignment of grid cells to
each processor.

.. important::

  See :ref:`Section 6.8<howto-details-grid-geometry-sparta>` of the
  manual for an explanation of clumped and dispersed grid cell
  assignments and their relative performance trade-offs.  The
  :ref:`balance_grid<balance-grid>` command can be used after the grid is
  read, to assign child cells to processors in different ways.  The "fix
  balance" command can be used to re-assign them in a load-balanced
  manner periodically during a running simulation.

The *custom* keyword allows for the creation of custom per-grid
attributes and specification of their values.  See the :ref:`Section 6.17<howto-custom-perparticl-pergrid,-persurf>` doc page for an explanation of
custom per-grid attributes.  Custom vectors or arrays associate a
single value or multiple values with each grid cell.  They can be
output by the :ref:`dump grid<dump>` command and used as inputs by
other commands.  For example, the
:ref:`create_particles<create-particles>` command can use per-grid
values to influence the creation of particles in each grid cell and
their properties.

The *name* argument is the name assigned to the new custom vector or
array.  The *datatytpe* argument is *int* or *float* which determines
whether the vector/array stores integer or floating point values.  The
*Nc* argument is 0 for a per-grid vector and an integer >= 1 for an
array with *Nc* columns.  A per-grid vector stores a single value per
grid cell; a per-grid array stores Nc values per grid cell.

Each use of the *custom* keyword determines how many values are
appended to each line following the grid cell ID.  For a custom
per-grid vector, a single value is appended.  For a custom per-grid
array, Nc values are appended.  The values are assigned to custom
vectors or arrays in the order the *custom* keywords are specified.
For example, for this read_grid command, 4 custom values should be
added to the end of each line in the Cells section of the input file:

::

   read_grid grid.data custom temperature float 0 custom flags int 3

The first floating-point value will be the assigned to a custom
per-grid vector named temperature which stores a single value per grid
cell.  The next 3 integers will be assigned to a custom per-grid array
named flags which stores 3 values per grid cell.

.. _read-grid-restrictio:

*************
Restrictions:
*************

This command can only be used after the simulation box is defined by
the :ref:`create_box<create-box>` command.

To read gzipped grid files, you must compile SPARTA with the
-DSPARTA_GZIP option - see :ref:`Section 2.2<start-making-sparta>` of
the manual for details.

.. _read-grid-related-commands:

*****************
Related commands:
*****************

:ref:`create_box<create-box>`, :ref:`create_grid<create-grid>`,
:ref:`write_grid<write-grid>`

.. _read-grid-default:

********
Default:
********

none