From e6da584a764a0de1d2aad2cdea062857aa21b06f Mon Sep 17 00:00:00 2001 From: Steve Plimpton Date: Mon, 7 Nov 2022 11:41:59 -0700 Subject: [PATCH] doc pages --- doc/src/Howto_output.rst | 3 +- doc/src/fix_ave_chunk.rst | 23 +++++++++--- doc/src/fix_ave_grid.rst | 44 ++++++++++++++++++----- doc/src/fix_ttm.rst | 75 ++++++++++++++++++++++++--------------- 4 files changed, 101 insertions(+), 44 deletions(-) diff --git a/doc/src/Howto_output.rst b/doc/src/Howto_output.rst index bf04b39781..771ecad8f0 100644 --- a/doc/src/Howto_output.rst +++ b/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 ` doc page for more details. .. _disambiguation: diff --git a/doc/src/fix_ave_chunk.rst b/doc/src/fix_ave_chunk.rst index 3eb5a5c9f3..0dca00e4bb 100644 --- a/doc/src/fix_ave_chunk.rst +++ b/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 ` +command defines spatial bins, the fix ave/chunk command performs a +similar computation as the :doc:`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 ` 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 ` +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 ` command defines its own group as well as an @@ -530,12 +541,14 @@ Restrictions Related commands """""""""""""""" -:doc:`compute `, :doc:`fix ave/atom `, -:doc:`fix ave/histo `, :doc:`fix ave/time `, -:doc:`variable `, :doc:`fix ave/correlate ` +:doc:`compute `, :doc:`fix ave/atom `, `fix +:doc:ave/histo `, :doc:`fix ave/time `, +:doc:`variable `, :doc:`fix ave/correlate +:doc:`, `fix ave/atogrid ` + Default """"""" -The option defaults are norm = all, ave = one, bias = none, no file output, and -title 1,2,3 = strings as described above. +The option defaults are norm = all, ave = one, bias = none, no file +output, and title 1,2,3 = strings as described above. diff --git a/doc/src/fix_ave_grid.rst b/doc/src/fix_ave_grid.rst index e32560193a..153e558962 100644 --- a/doc/src/fix_ave_grid.rst +++ b/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 ` command when it uses chunks from the :doc:`compute chunk/atom ` command which -are 2d or 3d regular bins. The per-bin outputs in that case are -global; each processor stores a copy of the entire set of bin data. -Thus it is better to use this command when the grid is large and a -simulation is run on many processors. +are 2d or 3d regular bins. However, the per-bin outputs in that case +are global; each processor stores a copy of the entire set of bin +data. Thus it more efficient to use the fix ave/grid command when the +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 +` command which can treat a grid defined by the +:doc:`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 ` +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 ` 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 `, 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 -datums can be accessed by various :doc:`output commands -`. +for the per-grid array and "count" for the per-grid vector (if using +per-atom values). Both datums can be accessed by various :doc:`output +commands `. In per-atom mode, the per-grid array values calculated by this fix are treated as "intensive", since they are typically already normalized by diff --git a/doc/src/fix_ttm.rst b/doc/src/fix_ttm.rst index 2cbb0c7799..3aa1d2006e 100644 --- a/doc/src/fix_ttm.rst +++ b/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. -The lines can appear in any order. For example, the initial -electronic temperatures on a 1 by 2 by 3 grid could be specified in -the file as follows: +point indices ranging from 1 to Nxyz inclusive in each dimension. The +lines can appear in any order. For example, the initial electronic +temperatures on a 1 by 2 by 3 grid could be specified in the file as +follows: .. parsed-literal:: # UNITS: metal COMMENT: initial electron temperature - 0 0 0 1.0 - 0 0 1 1.0 - 0 0 2 1.0 - 0 1 0 2.0 - 0 1 1 2.0 - 0 1 2 2.0 + 1 1 1 1.0 + 1 1 2 1.0 + 1 1 3 1.0 + 1 2 1 2.0 + 1 2 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 -be suffixed by the timestep. The format of each output file is exactly +timesteps. The second value is the filename for output, which will be +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 ` 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 ` command which creates a file specific + to this fix which the :doc:`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 ` command using the :doc:`compute chunk/atom ` command to create a 3d -array of chunks consistent with the grid used by this fix. For the -fix ttm/grid command the same thing can be done using the :doc:`fix -ave/grid ` command and its per-grid values can be output -via the :doc:`dump grid ` command. +array of chunks consistent with the grid used by this fix. + +For the fix ttm/grid command the same thing can be done using the +:doc:`fix ave/grid ` command and its per-grid values can +be output via the :doc:`dump grid ` 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 -restart files, this means you cannot do "exact" restarts with this -fix, where the simulation continues on the same as if no restart had -taken place. However, in a statistical sense, a restarted simulation -should produce the same behavior. +The fix ttm/grid command also outputs an auxiliary file each time a +restart file is written, with the electron temperatures for each grid +cell. The format of this file is the same as that read by the +*infile* option explained above. The filename is the same as the +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 ` +command. None of the :doc:`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 -stores the electron temperature for each grid cell in temperature -:doc:`units `. which can be accessed by various :doc:`output -commands `. The length of the vector (distributed -across all processors) is Nx * Ny * Nz. For access by other commands, -the name of the single grid produced by fix ttm/grid is "grid". The -name of its per-grid data is "data". +The fix ttm/grid command also outputs a per-grid vector which stores +the electron temperature for each grid cell in temperature :doc:`units +`. which can be accessed by various :doc:`output commands +`. The length of the vector (distributed across all +processors) is Nx * Ny * Nz. For access by other commands, the name +of the single grid produced by fix ttm/grid is "grid". The name of +its per-grid data is "data". No parameter of the fixes can be used with the *start/stop* keywords of the :doc:`run ` command. The fixes are not invoked during @@ -408,6 +416,15 @@ 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 """"""""""""""""