:orphan:

.. index:: fix_custom

.. _fix-custom:

.. _fix-custom-command:

##################
fix custom command
##################

.. _fix-custom-syntax:

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

::

   fix ID custom Nfreq style action args ... action args ...

   - ID is documented in :ref:`fix<fix>` command
   - custom = style name of this fix command
   - Nfreq = reset custom values every this many steps
   - style = *particle* or *grid* or *surf*
   - action args = all remaining args are identical to those defined for the :ref:`custom<custom>` command

.. _fix-custom-examples:

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

::

   variable dvec particle (x+y)/2.0
   custom particle create dvec double 0
   custom surf create temp double 0 create vstream double 3

::

   fix 1 custom 1000 particle set dvec v_dvec air NULL
   fix 1 custom 10000 surf file surf.temp.\* 1 temp file surf.vstream.\* 3 vstream\[1\] vstream\[2\] vstream\[3\]
   fix 1 custom 10000 surf file surf.flow.\* 4 temp vstream\[1\] vstream\[2\] vstream\[3\]

See examples using many of the :ref:`custom<custom>` and :ref:`fix custom<fix-custom>` command actions in examples/custom

.. _fix-custom-descriptio:

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

Reset one or more custom attributes for particles, grid cells, or
surface elements.  This operation is performed once every *Nfreq*
timesteps.

The syntax for *actions* and their arguments are the same as for the
:ref:`custom<custom>` command with two differences.

First, only the *set*, *file*, and *file/coarse* actions are supported
for this fix.  The *create* and *remove* actions are not, since they
do not make sense to perform multiple times during a run.

Second, the *file* and *file/coarse* actions take a filename as an
argument.  The filename must contain a wildcard "\*" character which
will be replaced by the timestep.  This is to allow a sequence of
files to be read during the simulation.  The filename wildcard "\*"
cannot be used with the :ref:`custom<custom>` command.

All of the actions supported by this command reset the values of
custom attribute(s) which must already exist.  See the
:ref:`custom<custom>` and :ref:`read_surf<read-surf>` and
:ref:`read_grid<read-grid>` commands for different ways to define and
initialize custom attributes.

.. note::

  that the resetting of attributes by this fix takes place at the
  end of timesteps determined by *Nfreq*.  If custom attributes are
  output by a :ref:`dump<dump>` command on the same timestep, that takes
  place after this fix has performed the reset.  This means that if this
  fix and a dump command both reset/output every 1000 steps, then a dump
  file snapshot for step 3000 could include custom attributes which were
  reset at the end of step 3000.  But the new attribute values will not
  influence particles or grid cells or surface elements until the
  following step 3001 and beyond.

Also note that this command DOES NOT reset attribute values at the
beginning of any run, even if an input script contains multiple
:ref:`run<run>` commands.  For example, if *Nfreq* = 1000 and the input
script performs a series of 10000-step runs, then no resetting of
attributes takes place (due to this command) on timestep 0, before the
first run.  Likewise, between runs, this command DOES reset attribute
values at the end of the last step (10000, 20000, etc) of each run,
but DOES NOT reset them again before the first step of the next run.

.. important::

  If needed, resetting of custom values can be performed
  before the first run or between runs using the :ref:`custom<custom>`
  command.

.. important::

  If *Nfreq* triggers the reading of a file on the last
  step of the last run in the input script, then the
  wildcard-substituted filename (explained below) must exist.  This is
  the case, even though the new values will have no effect in the
  current input script, since there are no subsequent timestep
  operations which will use them.  Note, however that if a restart file
  is written on the last timestep, or following the last run, the
  updated custom values will be written to the restart file.

.. _fix-custom-restrictio:

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

none

.. _fix-custom-related-commands:

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

:ref:`custom<custom>`, :ref:`mixture<mixture>`, :ref:`group<group>`,
:ref:`region<region>`

.. _fix-custom-default:

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

none