doc pages

doc/src/Howto_output.rst

@@ -100,7 +100,8 @@ Per-grid data can come in two kinds: a vector of values (one per grid
 cekk), or a 2d array of values (multiple values per grid ckk).  The
 doc page for a "compute" or "fix" that generates data will specify
 names for both the grid(s) and datum(s) it produces, e.g. per-grid
-vectors or arrays, which can be referenced by other commands.
+vectors or arrays, which can be referenced by other commands.  See the
+:doc:`Howto grid <Howto_grid>` doc page for more details.
 
 .. _disambiguation:
 

doc/src/fix_ave_chunk.rst

@@ -112,6 +112,17 @@ or atoms in a spatial bin.  See the :doc:`compute chunk/atom
 page for details of how chunks can be defined and examples of how they
 can be used to measure properties of a system.
 
+Note that if the :doc:`compute chunk/atom <compute_chunk_atom>`
+command defines spatial bins, the fix ave/chunk command performs a
+similar computation as the :doc:`fix ave/grid <fix_ave_grid>` command.
+However, the per-bin outputs from the fix ave/chunk command are
+global; each processor stores a copy of the entire set of bin data.
+By contrast, the :doc:`fix ave/grid <fix_ave_grid>` command uses a
+distributed grid where each processor owns a subset of the bins.  Thus
+it is more efficient to use the :doc:`fix ave/grid <fix_ave_grid>`
+command when the grid is large and a simulation is run on many
+processors.
+
 Note that only atoms in the specified group contribute to the summing
 and averaging calculations.  The :doc:`compute chunk/atom
 <compute_chunk_atom>` command defines its own group as well as an
@@ -530,12 +541,14 @@ Restrictions
 Related commands
 """"""""""""""""
 
-:doc:`compute <compute>`, :doc:`fix ave/atom <fix_ave_atom>`,
+:doc:`compute <compute>`, :doc:`fix ave/atom <fix_ave_atom>`, `fix
-:doc:`fix ave/histo <fix_ave_histo>`, :doc:`fix ave/time <fix_ave_time>`,
+:doc:ave/histo <fix_ave_histo>`, :doc:`fix ave/time <fix_ave_time>`,
-:doc:`variable <variable>`, :doc:`fix ave/correlate <fix_ave_correlate>`
+:doc:`variable <variable>`, :doc:`fix ave/correlate
+:doc:<fix_ave_correlate>`, `fix ave/atogrid <fix_ave_grid>`
+     
 
 Default
 """""""
 
-The option defaults are norm = all, ave = one, bias = none, no file output, and
+The option defaults are norm = all, ave = one, bias = none, no file
-title 1,2,3 = strings as described above.
+output, and title 1,2,3 = strings as described above.

doc/src/fix_ave_grid.rst

@@ -70,7 +70,7 @@ Examples
 .. code-block:: LAMMPS
 
    fix 1 all ave/grid 10000 1 10000 10 10 10 fx fy fz c_myMSD[*]
-   fix 1 flow ave/chunk 100 10 1000 20 20 30 f_TTM:grid:data
+   fix 1 flow ave/grid 100 10 1000 20 20 30 f_TTM:grid:data
 
 Description
 """""""""""
@@ -84,13 +84,13 @@ produced by other computes or fixes.  This fix operates in either
 per-grid inputs in the same command.
 
 The grid created by this command is distributed; each processor owns
-the grid points that are within its sub-domain.  This is in contrast to
+the grid points that are within its sub-domain.  This is similar to
 the :doc:`fix ave/chunk <fix_ave_chunk>` command when it uses chunks
 from the :doc:`compute chunk/atom <compute_chunk_atom>` command which
-are 2d or 3d regular bins.  The per-bin outputs in that case are
+are 2d or 3d regular bins.  However, the per-bin outputs in that case
-global; each processor stores a copy of the entire set of bin data.
+are global; each processor stores a copy of the entire set of bin
-Thus it is better to use this command when the grid is large and a
+data.  Thus it more efficient to use the fix ave/grid command when the
-simulation is run on many processors.
+grid is large and a simulation is run on many processors.
 
 For per-atom mode, only atoms in the specified group contribute to the
 summing and averaging calculations.  For per-grid mode, the specified
@@ -123,6 +123,32 @@ keyword settings, as discussed below.
 
 ----------
 
+The *Nx*, *Ny*, and *Nz* arguements specify the size of the grid that
+overlays the simulation box.  For 2d simulations, *Nz* must be 1.  The
+*Nx*, *Ny*, *Nz* values can be any positive integer.  The grid can be
+very coarse compared to the particle count, or very fine.  If one or
+more of the values = 1, then bins are 2d planes or 1d slices of the
+simulation domain.  Note that if the total number of grid cells is
+small, it may be more efficient to use the doc:`fix ave/chunk
+<fix_ave_chunk>` command which can treat a grid defined by the
+:doc:`compute chunk/atom <compute_chunk_atom>` command as a global
+grid where each processor owns a copy of all the grid cells.  If *Nx*
+= *Ny* = *Nz* = 1 is used, the same calculation would be more
+efficiently performed by the doc:`fix ave/atom <fix_ave_atom>`
+command.
+
+If the simulation box size or shape changes during a simulation, the
+grid always conforms to the size/shape of the current simulation box.
+If one more dimensions have non-peridoic shrink-wrapped boundary
+conditions, as defined by the :doc:`boundary <boundary>` command, then
+the grid will extend over the (dynamic) shrink-wrapped extent in each
+dimension.  If the box shape is triclinic, as explained in :doc:`Howto
+triclinic <Howto_triclinic>`, then the grid is also triclinic; each
+grid cell is a small triclinic cell with the same shape as the
+simulation box.
+
+----------
+
 In both per-atom and per-grid mode, input values from a compute or fix
 that produces an array of values (multiple values per atom or per grid
 point), the bracketed index I can be specified using a wildcard
@@ -455,9 +481,9 @@ Ny * Nz.
 
 For access by other commands, the name of the single grid produced by
 this fix is "grid".  The names of its two per-grid datums are "data"
-for the per-grid array and "count" for the per-grid vector.  Both
+for the per-grid array and "count" for the per-grid vector (if using
-datums can be accessed by various :doc:`output commands
+per-atom values).  Both datums can be accessed by various :doc:`output
-<Howto_output>`.
+commands <Howto_output>`.
 
 In per-atom mode, the per-grid array values calculated by this fix are
 treated as "intensive", since they are typically already normalized by

doc/src/fix_ttm.rst

@@ -195,20 +195,20 @@ the '#' character.  Each line contains four numeric columns:
 ix,iy,iz,Temperature.  Empty or comment-only lines will be
 ignored. The number of lines must be equal to the number of
 user-specified grid points (Nx by Ny by Nz).  The ix,iy,iz are grid
-point indices ranging from 0 to nxnodes-1 inclusive in each dimension.
+point indices ranging from 1 to Nxyz inclusive in each dimension.  The
-The lines can appear in any order.  For example, the initial
+lines can appear in any order.  For example, the initial electronic
-electronic temperatures on a 1 by 2 by 3 grid could be specified in
+temperatures on a 1 by 2 by 3 grid could be specified in the file as
-the file as follows:
+follows:
 
 .. parsed-literal::
 
    # UNITS: metal COMMENT: initial electron temperature
-   0 0 0 1.0
+   1 1 1 1.0
-   0 0 1 1.0
+   1 1 2 1.0
-   0 0 2 1.0
+   1 1 3 1.0
-   0 1 0 2.0
+   1 2 1 2.0
-   0 1 1 2.0
+   1 2 2 2.0
-   0 1 2 2.0
+   1 2 3 2.0
 
 where the electronic temperatures along the y=0 plane have been set to
 1.0, and the electronic temperatures along the y=1 plane have been set
@@ -226,8 +226,8 @@ units used.
 
 The *outfile* keyword has 2 values.  The first value *Nout* triggers
 output of the electronic temperatures for each grid point every Nout
-timesteps.  The second value is the filename for output which will
+timesteps.  The second value is the filename for output, which will be
-be suffixed by the timestep.  The format of each output file is exactly
+suffixed by the timestep.  The format of each output file is exactly
 the same as the input temperature file. It will contain a comment in
 the first line reporting the date the file was created, the LAMMPS
 units setting in use, grid size and the current timestep.
@@ -236,16 +236,21 @@ units setting in use, grid size and the current timestep.
 
   The fix ttm/grid command does not support the *outfile* keyword.
   Instead you can use the :doc:`dump grid <dump>` command to output
-  the electronic temperature on the distributed grid to a dump file.
+  the electronic temperature on the distributed grid to a dump file or
+  the :doc:`restart <restart>` command which creates a file specific
+  to this fix which the :doc:`read restart <read_restart>` command
+  reads.  The file has the same format as the file the *infile* option
+  reads.
 
 For the fix ttm and fix ttm/mod commands, the corresponding atomic
 temperature for atoms in each grid cell can be computed and output by
 the :doc:`fix ave/chunk <fix_ave_chunk>` command using the
 :doc:`compute chunk/atom <compute_chunk_atom>` command to create a 3d
-array of chunks consistent with the grid used by this fix.  For the
+array of chunks consistent with the grid used by this fix.
-fix ttm/grid command the same thing can be done using the :doc:`fix
+
-ave/grid <fix_ave_grid>` command and its per-grid values can be output
+For the fix ttm/grid command the same thing can be done using the
-via the :doc:`dump grid <dump>` command.
+:doc:`fix ave/grid <fix_ave_grid>` command and its per-grid values can
+be output via the :doc:`dump grid <dump>` command.
 
 ----------
 
@@ -362,11 +367,14 @@ the operation of the fix continues in an uninterrupted fashion.  Note
 that the restart script must define the same size grid as the original
 script.
 
-Because the state of the random number generator is not saved in the
+The fix ttm/grid command also outputs an auxiliary file each time a
-restart files, this means you cannot do "exact" restarts with this
+restart file is written, with the electron temperatures for each grid
-fix, where the simulation continues on the same as if no restart had
+cell.  The format of this file is the same as that read by the
-taken place.  However, in a statistical sense, a restarted simulation
+*infile* option explained above.  The filename is the same as the
-should produce the same behavior.
+restart filename with ".ttm" appended.  This auxiliary file can be
+read in for a restared run by using the *infile* option for the fix
+ttm/grid command, following the :doc:`read_restart <read_restart>`
+command.
 
 None of the :doc:`fix_modify <fix_modify>` options are relevant to
 these fixes.
@@ -386,13 +394,13 @@ electronic subsystem energies reported at the end of the timestep.
 
 The vector values calculated are "extensive".
 
-The fix ttm/grid command also calculates a per-grid vector which
+The fix ttm/grid command also outputs a per-grid vector which stores
-stores the electron temperature for each grid cell in temperature
+the electron temperature for each grid cell in temperature :doc:`units
-:doc:`units <units>`. which can be accessed by various :doc:`output
+<units>`. which can be accessed by various :doc:`output commands
-commands <Howto_output>`.  The length of the vector (distributed
+<Howto_output>`.  The length of the vector (distributed across all
-across all processors) is Nx * Ny * Nz.  For access by other commands,
+processors) is Nx * Ny * Nz.  For access by other commands, the name
-the name of the single grid produced by fix ttm/grid is "grid".  The
+of the single grid produced by fix ttm/grid is "grid".  The name of
-name of its per-grid data is "data".
+its per-grid data is "data".
 
 No parameter of the fixes can be used with the *start/stop* keywords
 of the :doc:`run <run>` command.  The fixes are not invoked during
@@ -408,6 +416,15 @@ package <Build_package>` page for more info.
 As mentioned above, these fixes require 3d simulations and orthogonal
 simulation boxes periodic in all 3 dimensions.
 
+These fixes used a random number generator to Langevin thermostat the
+electron temperature.  This means you will not get identical answers
+when running on different numbers of processors or when restarting a
+simulation (even on the same number of processors).  However, in a
+statistical sense, simulations on different processor counts and
+restarted simulation should produce results whiich are statistically
+the same.
+
+
 Related commands
 """"""""""""""""