<HTML>
<CENTER><A HREF = "https://sparta.github.io">SPARTA WWW Site</A> - <A HREF = "Manual.html">SPARTA Documentation</A> - <A HREF = "Section_commands.html#comm">SPARTA Commands</A> 
</CENTER>






<HR>

<H3>read_grid command 
</H3>
<P><B>Syntax:</B>
</P>
<PRE>read_grid filename keyword args ... 
</PRE>
<UL><LI>filename = name of grid file 

<LI>zero or more keyword/args pairs may be appended 

<LI>keyword = <I>custom</I> 

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

</UL>
<P><B>Examples:</B>
</P>
<PRE>read_grid data.grid
read_grid data.grid custom temperature double 0 
</PRE>
<P><B>Description:</B>
</P>
<P>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 <A HREF = "create_box.html">create_box</A> command.  The grid
can also be defined by the <A HREF = "create_grid.html">create_grid</A> command.
</P>
<P>The grid file can be written by the <A HREF = "write_grid.html">write_grid</A>
command in a previous simulation, or be created by some pre-processing
tool.  See <A HREF = "Section_howto.html#howto_8">Section 6.8</A> of the manual for
a definition of hierarchical grids and grid cell IDs as used by
SPARTA.  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.
</P>
<P>The specified file can be a text file or a gzipped text file (detected
by a .gz suffix).  See the <A HREF = "write.grid.html">write_grid</A> command for a
description of the format of the file.
</P>
<P>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.
</P>
<P>IMPORTANT NOTE: See <A HREF = "Section_howto.html#howto_8">Section 6.8</A> of the
manual for an explanation of clumped and dispersed grid cell
assignments and their relative performance trade-offs.  The
<A HREF = "balance_grid.html">balance_grid</A> 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.
</P>
<P>The <I>custom</I> keyword allows a custom per-grid vector or array to be
created and initialized.  Custom vectors or arrays associate a single
value or multiple values with each grid cell.  They can be output by
the <A HREF = "dump.html">dump grid</A> command and uses as inputs by other
commands.  For example, many of the models for the
<A HREF = "surf_collide.html">surf_collide</A> command take temperature as an input;
use of a per-surf vector allows the temperature of individual surface
elements to be specified.
</P>
<P>The <I>name</I> argument is the name assigned to the new custom vector or
array.  The <I>datatytpe</I> argument is <I>int</I> or <I>float</I> which determines
whether the vector/array stores integer or floating point values.  The
<I>Nc</I> argument is 0 for a per-surgrid vector and an integer >= 1 for an
array with <I>Nc</I> columns.  A per-grid vector stores a single value per
grid cell; a per-grid array stores Nc values per grid cell.
</P>
<P>Each use of the <I>custom</I> keyword determines how many values are
appended for 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 <I>custom</I> 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:
</P>
<PRE>read_grid grid.data custom temperature float 0 custom flags int 3 
</PRE>
<P>The first floating-point value will be the temperature, the next 3
integers will be flags.
</P>
<P><B>Restrictions:</B>
</P>
<P>This command can only be used after the simulation box is defined by
the <A HREF = "create_box.html">create_box</A> command.
</P>
<P>To read gzipped grid files, you must compile SPARTA with the
-DSPARTA_GZIP option - see <A HREF = "Section_start.html#start_2">Section 2.2</A> of
the manual for details.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "create_box.html">create_box</A>, <A HREF = "create_grid.html">create_grid</A>,
<A HREF = "write_grid.html">write_grid</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>
