diff --git a/doc/compute_rdf.html b/doc/compute_rdf.html new file mode 100644 index 000000000..2fd33f36b --- /dev/null +++ b/doc/compute_rdf.html @@ -0,0 +1,130 @@ +<HTML> +<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> +</CENTER> + + + + + + +<HR> + +<H3>compute rdf command +</H3> +<P><B>Syntax:</B> +</P> +<PRE>compute ID group-ID rdf Nbin itype1 jtype1 itype2 jtype2 ... +</PRE> +<UL><LI>ID, group-ID are documented in <A HREF = "compute.html">compute</A> command +<LI>rdf = style name of this compute command +<LI>Nbin = number of RDF bins +<LI>itypeN = central atom type for Nth RDF histogram (see asterisk form below) +<LI>jtypeN = distribution atom type for Nth RDF histogram (see asterisk form below) +</UL> +<P><B>Examples:</B> +</P> +<PRE>fix 1 all rdf 100 +fix 1 all rdf 100 1 1 +fix 1 all rdf 100 * 3 +fix 1 fluid rdf 500 1 1 1 2 2 1 2 2 +fix 1 fluid rdf 500 1*3 2 5 *10 +</PRE> +<P><B>Description:</B> +</P> +<P>Define a computation that calculates the radial distribution function +(RDF), also called g(r), and the coordination number for a group of +particles. Both are calculated in histogram form by binning pairwise +distances into <I>Nbin</I> bins from 0.0 to the maximum force cutoff +defined by the <A HREF = "pair_style.html">pair_style</A> command. The bins are of +uniform size in radial distance. Thus a single bin encompasses a thin +shell of distances in 3d and a thin ring of distances in 2d. +</P> +<P>The <I>itypeN</I> and <I>jtypeN</I> arguments are optional. These arguments +must come in pairs. If no pairs are listed, then a single histogram +is computed for g(r) between all atom types. If one or more pairs are +listed, then a separate histogram is generated for each +<I>itype</I>,<I>jtype</I> pair. +</P> +<P>The <I>itypeN</I> and <I>jtypeN</I> settings can be specified in one of two +ways. An explicit numeric value can be used, as in the 4th example +above. Or a wild-card asterisk can be used to specify a range of atom +types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the +number of atom types, then an asterisk with no numeric values means +all types from 1 to N. A leading asterisk means all types from 1 to n +(inclusive). A trailing asterisk means all types from n to N +(inclusive). A middle asterisk means all types from m to n +(inclusive). +</P> +<P>If both <I>itypeN</I> and <I>jtypeN</I> are single values, as in the 4th example +above, this means that a g(r) is computed where atoms of type <I>itypeN</I> +are the central atom, and atoms of type <I>jtypeN</I> are the distribution +atom. If either <I>itypeN</I> and <I>jtypeN</I> represent a range of values via +the wild-card asterisk, as in the 5th example above, this means that a +g(r) is computed where atoms of any of the range of types represented +by <I>itypeN</I> are the central atom, and atoms of any of the range of +types represented by <I>jtypeN</I> are the distribution atom. +</P> +<P>Pairwise distances are generated by looping over a pairwise neighbor +list, just as they would be in a <A HREF = "pair_style.html">pair_style</A> +computation. The distance between two atoms I and J is included in +a specific histogram if the following criteria are met: +</P> +<UL><LI>atoms I,J are both in the specified fix group +<LI>the distance between atoms I,J is less than the maximum force cutoff +<LI>the type of the I atom matches itypeN (one or a range of types) +<LI>the type of the J atom matches jtypeN (one or a range of types) +<LI>the I,J interaction is included in the neighbor list +</UL> +<P>The last point is relevant for molecular systems with bonds, because +if two atoms I,J are involved in 1-2, 1-3, 1-4 interactions within the +molecular topology, their pairwise interaction may be turned off, and +thus they will not appear in the neighbor list, and will not +contribute to g(r). More specifically, this is true of pairs with a +weighting factor of 0.0; pairs with a non-zero weighting factor are +included. The weighting factors for 1-2, 1-3, and 1-4 pairwise +interactions is set by the <A HREF = "special_bonds.html">special_bonds</A> command. +</P> +<P>It is OK if a particular pairwise distance is included in more than +one individual histogram, due to the way the <I>itypeN</I> and <I>jtypeN</I> +arguments are specified. +</P> +<P>The g(r) value for a bin is calculated from the histogram count by +scaling it by the idealized number of how many counts there would be +if atoms of type <I>jtypeN</I> were uniformly distributed. Thus it +involves the count of <I>itypeN</I> atoms, the count of <I>jtypeN</I> atoms, the +volume of the entire simulation box, and the volume of the thin bin +shell in 3d (or the area of the thin bin ring in 2d). +</P> +<P>A coordination number coord(r) is also calculated, which is the sum of +g(r) values for all bins up to and including the current bin. +</P> +<P><B>Output info:</B> +</P> +<P>This compute calculates a global array with the number of rows = +<I>Nbins</I>, and the number of columns = 1 + 2*Npairs, where Npairs is the +number of I,J pairings specified. The first column has the bin +coordinate (center of the bin), Each successive set of 2 columns has +the g(r) and coord(r) values for a specific set of <I>itypeN</I> versus +<I>jtypeN</I> interactions, as described above. These values can be used +by any command that uses a global values from a compute as input. See +<A HREF = "Section_howto.html#4_15">this section</A> for an overview of LAMMPS +output options. +</P> +<P>The array values calculated by this compute are all "intensive", since +they are normalized, meaning they are independent of the number of +atoms in the simulation. +</P> +<P><B>Restrictions:</B> +</P> +<P>The RDF is not computed for distances longer than the force cutoff, +since processors (in parallel) don't know about atom coordinates for +atoms further away than that distance. If you want an RDF for larger +distances, you'll need to post-process a dump file. +</P> +<P><B>Related commands:</B> +</P> +<P><A HREF = "fix_ave_histo.html">fix ave/histo</A> +</P> +<P><B>Default:</B> none +</P> +</HTML> diff --git a/doc/compute_rdf.txt b/doc/compute_rdf.txt new file mode 100644 index 000000000..9c1205026 --- /dev/null +++ b/doc/compute_rdf.txt @@ -0,0 +1,125 @@ +"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Section_commands.html#comm) + +:line + +compute rdf command :h3 + +[Syntax:] + +compute ID group-ID rdf Nbin itype1 jtype1 itype2 jtype2 ... :pre + +ID, group-ID are documented in "compute"_compute.html command +rdf = style name of this compute command +Nbin = number of RDF bins +itypeN = central atom type for Nth RDF histogram (see asterisk form below) +jtypeN = distribution atom type for Nth RDF histogram (see asterisk form below) :ul + +[Examples:] + +fix 1 all rdf 100 +fix 1 all rdf 100 1 1 +fix 1 all rdf 100 * 3 +fix 1 fluid rdf 500 1 1 1 2 2 1 2 2 +fix 1 fluid rdf 500 1*3 2 5 *10 :pre + +[Description:] + +Define a computation that calculates the radial distribution function +(RDF), also called g(r), and the coordination number for a group of +particles. Both are calculated in histogram form by binning pairwise +distances into {Nbin} bins from 0.0 to the maximum force cutoff +defined by the "pair_style"_pair_style.html command. The bins are of +uniform size in radial distance. Thus a single bin encompasses a thin +shell of distances in 3d and a thin ring of distances in 2d. + +The {itypeN} and {jtypeN} arguments are optional. These arguments +must come in pairs. If no pairs are listed, then a single histogram +is computed for g(r) between all atom types. If one or more pairs are +listed, then a separate histogram is generated for each +{itype},{jtype} pair. + +The {itypeN} and {jtypeN} settings can be specified in one of two +ways. An explicit numeric value can be used, as in the 4th example +above. Or a wild-card asterisk can be used to specify a range of atom +types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the +number of atom types, then an asterisk with no numeric values means +all types from 1 to N. A leading asterisk means all types from 1 to n +(inclusive). A trailing asterisk means all types from n to N +(inclusive). A middle asterisk means all types from m to n +(inclusive). + +If both {itypeN} and {jtypeN} are single values, as in the 4th example +above, this means that a g(r) is computed where atoms of type {itypeN} +are the central atom, and atoms of type {jtypeN} are the distribution +atom. If either {itypeN} and {jtypeN} represent a range of values via +the wild-card asterisk, as in the 5th example above, this means that a +g(r) is computed where atoms of any of the range of types represented +by {itypeN} are the central atom, and atoms of any of the range of +types represented by {jtypeN} are the distribution atom. + +Pairwise distances are generated by looping over a pairwise neighbor +list, just as they would be in a "pair_style"_pair_style.html +computation. The distance between two atoms I and J is included in +a specific histogram if the following criteria are met: + +atoms I,J are both in the specified fix group +the distance between atoms I,J is less than the maximum force cutoff +the type of the I atom matches itypeN (one or a range of types) +the type of the J atom matches jtypeN (one or a range of types) +the I,J interaction is included in the neighbor list :ul + +The last point is relevant for molecular systems with bonds, because +if two atoms I,J are involved in 1-2, 1-3, 1-4 interactions within the +molecular topology, their pairwise interaction may be turned off, and +thus they will not appear in the neighbor list, and will not +contribute to g(r). More specifically, this is true of pairs with a +weighting factor of 0.0; pairs with a non-zero weighting factor are +included. The weighting factors for 1-2, 1-3, and 1-4 pairwise +interactions is set by the "special_bonds"_special_bonds.html command. + +It is OK if a particular pairwise distance is included in more than +one individual histogram, due to the way the {itypeN} and {jtypeN} +arguments are specified. + +The g(r) value for a bin is calculated from the histogram count by +scaling it by the idealized number of how many counts there would be +if atoms of type {jtypeN} were uniformly distributed. Thus it +involves the count of {itypeN} atoms, the count of {jtypeN} atoms, the +volume of the entire simulation box, and the volume of the thin bin +shell in 3d (or the area of the thin bin ring in 2d). + +A coordination number coord(r) is also calculated, which is the sum of +g(r) values for all bins up to and including the current bin. + +[Output info:] + +This compute calculates a global array with the number of rows = +{Nbins}, and the number of columns = 1 + 2*Npairs, where Npairs is the +number of I,J pairings specified. The first column has the bin +coordinate (center of the bin), Each successive set of 2 columns has +the g(r) and coord(r) values for a specific set of {itypeN} versus +{jtypeN} interactions, as described above. These values can be used +by any command that uses a global values from a compute as input. See +"this section"_Section_howto.html#4_15 for an overview of LAMMPS +output options. + +The array values calculated by this compute are all "intensive", since +they are normalized, meaning they are independent of the number of +atoms in the simulation. + +[Restrictions:] + +The RDF is not computed for distances longer than the force cutoff, +since processors (in parallel) don't know about atom coordinates for +atoms further away than that distance. If you want an RDF for larger +distances, you'll need to post-process a dump file. + +[Related commands:] + +"fix ave/histo"_fix_ave_histo.html + +[Default:] none