<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>write_surf command 
</H3>
<P><B>Syntax:</B>
</P>
<PRE>write_surf file 
</PRE>
<UL><LI>file = name of file to write surface element info to 

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

<LI>keyword = <I>points</I> or <I>type</I> or <I>custom</I> or <I>fileper</I> or <I>nfile</I> 

<PRE>  <I>points</I> arg = <I>yes</I> or <I>no</I> to include a Points section in the file
  <I>type</I> arg = none
  <I>custom</I> arg = name
    name = name of custom per-surf vector or array
  <I>fileper</I> arg = Np
    Np = write one file for every this many processors
  <I>nfile</I> arg = Nf
    Nf = write this many files, one from each of Nf processors 
</PRE>

</UL>
<P><B>Examples:</B>
</P>
<PRE>write_surf data.surf
write_surf data.surf type custom temperature custom flags
write_surf data.surf points no
write_surf data.surf.% nfile 50 
</PRE>
<P><B>Description:</B>
</P>
<P>Write a surface file in text format describing the currently defined
surface elements, whether they be explicit or implicit surfaces.  See
the <A HREF = "read_surf.html">read_surf</A> and <A HREF = "read_isurf.html">read_isurf</A>
commands for a definition of surface elements and how they are defined
and used be SPARTA.  The surface file can be used for later input to a
new simulation or for post-processing and visualization.
</P>
<P>Note that if surface objects were clipped when read in by the
<A HREF = "read_surf.html">read_surf</A> command then some surface elements may have
been deleted and new ones created.  Likewise for the points that
define the end points or corner points of surface element lines (2d)
or triangles (3d).  Similarly, if surface elements have been removed
by the <A HREF = "remove_surf.html">remove_surf</A> command, then points may have
also been deleted.  In either case, surface points and elements are
renumbered by these operations to create compressed, contiguous lists.
These lists of surface elements are what is output by this command.
</P>
<P>The output file is written as a text file in the same format as the
file the <A HREF = "read_surf.html">read_surf</A> command reads for explicit
surfaces.  See the <A HREF = "read_surf.html">read_surf</A> doc page for a
description of its format.
</P>
<P>Similar to <A HREF = "dump.html">dump</A> files, the surface filename can contain
two wild-card characters.  If a "*" appears in the filename, it is
replaced with the current timestep value.  If a "%" character appears
in the filename, then one file is written by each processor and the
"%" character is replaced with the processor ID from 0 to P-1.  An
additional file with the "%" replaced by "base" is also written, which
contains global information, i.e. just the header information for the
number of points and lines or triangles, as described on the
<A HREF = "read_surf.html">read_surf</A> doc page.
</P>
<P>For example, the files written for filename data.% would be data.base,
data.0, data.1, ..., data.P-1.  This creates smaller files and can be
a fast mode of output and subsequent input on parallel machines that
support parallel I/O.  The optional <I>fileper</I> and <I>nfile</I> keywords
discussed below can alter the number of files written.
</P>
<P>Note that implicit surfaces read in by the
<A HREF = "read_isurf.html">read_isurf</A> command can be written out by the
write_surf command, e.g. for visualization purposes or to start a
second simulation treating implicit surfaces previously ablated via
the <A HREF = "fix_ablate.html">fix ablate</A> command as constant, unchanging
explicit surfaces.  Because this command creates files in an explicit
surface format, it can only be read back in to SPARTA via the
<A HREF = "read_surf.html">read_surf</A> command.  It cannot be read back in via the
<A HREF = "read_isurf.html">read_isurf</A> command.
</P>
<P>Also note, that implicit surfaces use the grid cell ID as the surface
element ID for all line segments (2d) or triangles (3d) in the same
grid cell.  When this command writes them to a file, the surface
element IDs in the file become integers between 1 and N, where N is
the total number of implicit surface elements.
</P>
<P>See the <A HREF = "Section_howto.html#howto_13">Howto 6.13</A> section of the manual
for a discussion of explicit and implicit surfaces as well as
distributed versus non-distributed storage of surface elements.  You
cannot mix explicit and implicit surfaces in the same simulation.
</P>
<HR>

<P>The following optional keywords can be used with this command.
</P>
<P>If the <I>points</I> keyword is specified with a value of <I>yes</I>, then a
Points section is included in the written file.  The Lines or
Triangles section will reference indices from the Points section.  If
the <I>points</I> keyword is specified with a value of <I>no</I>, then a Points
section is not included. The Lines or Triangles section will list the
coordinates of line segment or trianges corners directly.
</P>
<P>If the <I>type</I> keyword is specified, then a surface element type is
included for each line or triangle in the Lines or Triangles section.
If it is not specified, element types are not incuded.
</P>
<P>If the <I>custom</I> keyword is specified along with the <I>name</I> of a custom
per-surf vector or array, then the per-surf values for that vector or
array are added to the end of the line of output for each line or
triangle in the Lines or Triangles section.  A per-surf vector is a
single value per element; a per-surf array is 1 or more values per
element, depending on how it was defined.  If the <I>custom</I> keyword is
used multiple times, then the value(s) for each <I>name</I> are appended in
the order the <I>custom</I> keywords are specified.
</P>
<P>The <I>nfile</I> or <I>fileper</I> keywords can be used in conjunction
with the "%" wildcard character in the specified surface file name.
As explained above, the "%" character causes the surface file to be
written in pieces, one piece for each of P processors.  By default P =
the number of processors the simulation is running on.  The <I>nfile</I> or
<I>fileper</I> keyword can be used to set P to a smaller value, which can
be more efficient when running on a large number of processors.
</P>
<P>The <I>nfile</I> keyword sets P to the specified Nf value.  For example, if
Nf = 4, and the simulation is running on 100 processors, 4 files will
be written, by processors 0,25,50,75.  Each will collect information
from itself and the next 24 processors and write it to a surface file.
</P>
<P>For the <I>fileper</I> keyword, the specified value of Np means write one
file for every Np processors.  For example, if Np = 4, every 4th
processor (0,4,8,12,etc) will collect information from itself and the
next 3 processors and write it to a surface file.
</P>
<HR>

<P><B>Restrictions:</B>
</P>
<P>The <I>custom</I> keyword cannot be used with implicit surfaces.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "read_surf.html">read_surf</A>, <A HREF = "read_isurf.html">read_isurf</A>
</P>
<P><B>Default:</B>
</P>
<P>The default is points = yes.  If the <I>fileper</I> or <I>nfile</I> keywords are
not used, a single file is written.
</P>
</HTML>
