<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>custom command 
</H3>
<P><B>Syntax:</B>
</P>
<PRE>custom style attribute action args ... keyword value ... 
</PRE>
<UL><LI>style = <I>particle</I> or <I>grid</I> or <I>surf</I> 

<LI>attribute = name of custom attribute 

<PRE>  name = custom vector attribute with name
  name[N] = Nth column of custom array attribute with name 
</PRE>
<LI>action = <I>set</I> or <I>remove</I> 

<PRE>  <I>set</I> args = v_name subset-ID region-ID
    v_name = equal-, particle-, grid-, or surf-style variable with name
    subset-ID = mixture ID (particles) or group ID (grid cells or surf elements)
    region-ID = only apply to particle/grid/surf in region, NULL to not test
  <I>remove</I> args = none 
</PRE>
<LI>zero of more keyword/arg pairs may be appended (only for action = set) 

<PRE>keyword = <I>type</I> or <I>size</I>
  <I>type</I> arg = <I>int</I> or <I>float</I>
  <I>size</I> arg = M for number of columns in a new custom array 
</PRE>

</UL>
<P><B>Examples:</B>
</P>
<PRE>variable ivec particle id/100000
variable sdvec surf c_1*10+3.5
variable sdarray1 surf s_dvec+1
variable sdarray2 surf v_sdarray1+1 
</PRE>
<PRE>custom particle ivec set v_ivec air NULL type int
custom surf dvec set v_sdvec all NULL
custom surf darray[1] set v_sdarray1 all NULL size 2
custom surf darray[2] set v_sdarray2 all NULL
custom particle ivec remove
custom surf darray remove 
</PRE>
<P><B>Description:</B>
</P>
<P>Create or reset or remove a custom attribute for individual particles,
grid cells, or surface elements.  To create or reset an attribute a
variable is specified and evaluated.  Custom attributes can be can be
vectors (single value per entity) or arrays (mutiple values per
entity).  They can also be integer or floating point values.  See
<A HREF = "Section_howto.html#howto_17">Section 6.17</A> for more discussion of
custom attributes.
</P>
<P>The specified <I>style</I> setting is <I>particle</I> or <I>grid</I> or <I>surf</I>
for per-particle, per-grid, or per-surf attributes.
</P>
<P>The <I>attribute</I> specifies the name of the attribute to operate on.
The same name can be used for attributes of different styles.
E.g. there can be a custom attribute with the name "flag" for both
particles and surface elements.  If the attribute name is specified
without brackets, it refers to a custom vector (single value per
entity).  If the attribute name is specified with a bracketed integer,
it refers to the column of a custom array (one or more values per
entity).  The integer <I>N</I> must be between 1 and M = # of columns in
the array (values per entity).  See the <I>size</I> keyword discussion
below for how to specify M if it is a new custom array.
</P>
<P>The <I>action</I> is specified as <I>set</I> or <I>remove</I>.
</P>
<P>If <I>remove</I> is used, then the <I>attribute</I> should be simply the name of
the attribute, whether it is a vector or array.  No trailing brackets
are specified.  The attribute will be removed from the system.  No
further arguments can be specified.
</P>
<P>If <I>set</I> is used, then the attribute is created if it does not already
exist and its values are initialized.  If it already exists, its
values are reset.  Custom attributes can be vectors (single value per
entity) or arrays (mutiple values per entity).  To set the values for
a custom vector, use an <I>attribute</I> name without brackets,
e.g. temperature.  To set the values for a single column of a custom
array, use an <I>attribute</I> name suffixed by a bracketed integer,
e.g. dipole[3].  The integer must be a value from 1 to M, where M is
the number of columns (values per entity) in the array.
</P>
<P>The specified <I>v_name</I> is the name of a previously defined variable
which this command will evaluate.  It must be either an equal-style or
particle-style or grid-style or surf-style variable.  All of these
styles define a mathematical formula which is used to compute the
value(s) of the variable.  See the <A HREF = "variable.html">variable</A> for
details.
</P>
<P>If an equal-style variable is specified, it produces a single value
which will be assigned as the custom value to all particles or grid
cells or surface elements.  Otherwise a particle-style variable must
be used for style = <I>particle</I>, a grid-style variable for style =
<I>grid</I>, or a surf-style variable for style = <I>surf</I>.  When it is
evaluated it generates one value for each particle, grid cell, or
surface element, which is assigned to the custom vector or to a column
of the custom array.
</P>
<P>Note that the latter 3 variable styles can include outputs from
<A HREF = "compute.html">compute</A> or <A HREF = "fix.html">fix</A> commands.  They can also
include the current timestep or the spatial position of a particle,
grid cell, or surface element in their formula. So it is easy to
calculate values for each entity which vary spatially or which depend
on the current timestep.
</P>
<P>The next two arguments, <I>subset-ID</I> and <I>region-ID</I>, can limit which
particles, grid cells, or surface elements are assigned a custom
value.  An individual particle, grid cell, or surface element must
meet both criteria to have its custom value set, otherwise its value
is set to zero.
</P>
<P>The <I>subset-ID</I> is the ID of a mixture for particles or the ID of a
group of grid cells or surface elements.  Only particles in the
mixture or grid cells/surface elements in the group will be assigned a
value.  See the <A HREF = "mixture.html">mixture</A> and <A HREF = "group.html">group</A> commands
for more details.  Note that "all" is a pre-defined mixture ID which
contains all particles.  Likewise "all" is the name of a pre-defined
group with all grid cells or surface elements.
</P>
<P>The <I>region-ID</I> is the ID of a geometric region defined by the
<A HREF = "region.html">region</A> command.  Only particles or grid cells or surface
elements in the region will have their values set.  The center point
of a grid cell or surface element is used for the region check.  If
<I>region-ID</I> is specified as NULL, then the region criterion is not
applied.
</P>
<P>Two optional keywords affect the creation of a new custom vector or
array.  They are ignored if the custom vector or array already exists.
</P>
<P>The <I>type</I> keyword can be used with <I>int</I> or <I>float</I> as its arg.  The
created custom attribute will then store either integer or
floating-point values.  Floating point values are the default.
</P>
<P>The <I>size</I> keyword can be used with arg = 0 to create a custom vector
(which is the default).  It can also be used with an arg M >= 1 to
create an array with M columns (values per entity).  This means that
if a new <I>attribute</I> name is specified with no brackets, the <I>size</I>
keyword is not necessary, because it's default value refers to a
custom vector.  But if a new <I>attribute</I> name with a bracket is used,
the <I>size</I> keyword must be used so that the column dimension of the
array is known.
</P>
<HR>

<P><B>Restrictions:</B> none
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "mixture.html">mixture</A>, <A HREF = "group.html">group</A>, <A HREF = "region.html">region</A>
</P>
<P><B>Default:</B>
</P>
<P>The default settings for creation of a new custom attibute are type =
float and size = 0.
</P>
</HTML>
