jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@13237 f3b2605a-c512-4ea7-a41b-209d697bcdaa

This commit is contained in:
sjplimp 2015-03-17 16:05:28 +00:00
parent fb2a894e03
commit 220bb4df5e
16 changed files with 1685 additions and 305 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/Manual.html
View File

@ -245,17 +245,21 @@ it gives quick access to documentation for all LAMMPS commands.
<BR></UL>
<LI><A HREF = "Section_python.html">Python interface</A>
<UL> 11.1 <A HREF = "Section_python.html#py_1">Building LAMMPS as a shared library</A>
<UL> 11.1 <A HREF = "Section_python.html#py_1">Overview of running LAMMPS from Python</A>
<BR>
11.2 <A HREF = "Section_python.html#py_2">Installing the Python wrapper into Python</A>
11.2 <A HREF = "Section_python.html#py_2">Overview of using Python from a LAMMPS script</A>
<BR>
11.3 <A HREF = "Section_python.html#py_3">Extending Python with MPI to run in parallel</A>
11.3 <A HREF = "Section_python.html#py_3">Building LAMMPS as a shared library</A>
<BR>
11.4 <A HREF = "Section_python.html#py_4">Testing the Python-LAMMPS interface</A>
11.4 <A HREF = "Section_python.html#py_4">Installing the Python wrapper into Python</A>
<BR>
11.5 <A HREF = "Section_python.html#py_5">Using LAMMPS from Python</A>
11.5 <A HREF = "Section_python.html#py_5">Extending Python with MPI to run in parallel</A>
<BR>
11.6 <A HREF = "Section_python.html#py_6">Example Python scripts that use LAMMPS</A>
11.6 <A HREF = "Section_python.html#py_6">Testing the Python-LAMMPS interface</A>
<BR>
11.7 <A HREF = "py_7">Using LAMMPS from Python</A>
<BR>
11.8 <A HREF = "py_8">Example Python scripts that use LAMMPS</A>
<BR></UL>
<LI><A HREF = "Section_errors.html">Errors</A>

14
doc/Manual.txt
View File

@ -159,12 +159,14 @@ it gives quick access to documentation for all LAMMPS commands.
10.14 "Variable options"_mod_14 :b
10.15 "Submitting new features for inclusion in LAMMPS"_mod_15 :ule,b
"Python interface"_Section_python.html :l
11.1 "Building LAMMPS as a shared library"_py_1 :ulb,b
11.2 "Installing the Python wrapper into Python"_py_2 :b
11.3 "Extending Python with MPI to run in parallel"_py_3 :b
11.4 "Testing the Python-LAMMPS interface"_py_4 :b
11.5 "Using LAMMPS from Python"_py_5 :b
11.6 "Example Python scripts that use LAMMPS"_py_6 :ule,b
11.1 "Overview of running LAMMPS from Python"_py_1 :ulb,b
11.2 "Overview of using Python from a LAMMPS script"_py_2 :b
11.3 "Building LAMMPS as a shared library"_py_3 :b
11.4 "Installing the Python wrapper into Python"_py_4 :b
11.5 "Extending Python with MPI to run in parallel"_py_5 :b
11.6 "Testing the Python-LAMMPS interface"_py_6 :b
11.7 "Using LAMMPS from Python"_py_7 :b
11.8 "Example Python scripts that use LAMMPS"_py_8 :ule,b
"Errors"_Section_errors.html :l
12.1 "Common problems"_err_1 :ulb,b
12.2 "Reporting bugs"_err_2 :b

117
doc/Section_commands.html
View File

@ -86,11 +86,12 @@ file names or user-chosen ID strings.
</P>
<P>Here is how each line in the input script is parsed by LAMMPS:
</P>
<P>(1) If the last printable character on the line is a "&" character
(with no surrounding quotes), the command is assumed to continue on
the next line. The next line is concatenated to the previous line by
removing the "&" character and newline. This allows long commands to
be continued across two or more lines.
<P>(1) If the last printable character on the line is a "&" character,
the command is assumed to continue on the next line. The next line is
concatenated to the previous line by removing the "&" character and
line break. This allows long commands to be continued across two or
more lines. See the discussion of triple quotes in (6) for how to
continue a command across multiple line without using "&" characters.
</P>
<P>(2) All characters from the first "#" character onward are treated as
comment and discarded. See an exception in (6). Note that a
@ -136,9 +137,9 @@ variable X delete
contain nested $ characters for other variables to substitute for.
Thus you cannot do this:
</P>
<PRE>variable a equal 2
variable b2 equal 4
region 1 block ${b$a} 2 INF INF EDGE EDGE
<PRE>variable a equal 2
variable b2 equal 4
print "B2 = ${b$a}"
</PRE>
<P>Nor can you specify this $($x-1.0) for an immediate variable, but
you could use $(v_x-1.0), since the latter is valid syntax for an
@ -156,27 +157,38 @@ underscores, or punctuation characters.
line are arguments.
</P>
<P>(6) If you want text with spaces to be treated as a single argument,
it can be enclosed in either double or single quotes. A long single
argument enclosed in quotes can even span multiple lines if the "&"
character is used, as described above. E.g.
it can be enclosed in either single or double or triple quotes. A
long single argument enclosed in single or double quotes can span
multiple lines if the "&" character is used, as described above. When
the lines are concatenated together (and the "&" characters and line
breaks removed), the text will become a single line. If you want
multiple lines of an argument to retain their line breaks, the text
can be enclosed in triple quotes, in which case "&" characters are not
needed. For example:
</P>
<PRE>print "Volume = $v"
print 'Volume = $v'
if "$<I>steps</I> > 1000" then quit
variable a string "red green blue &
purple orange cyan"
if "$<I>steps</I> > 1000" then quit
print """
System volume = $v
System temperature = $t
"""
</PRE>
<P>The quotes are removed when the single argument is stored internally.
<P>In each case, the single, double, or triple quotes are removed when
the single argument they enclose is stored internally.
</P>
<P>See the <A HREF = "dump_modify.html">dump modify format</A> or <A HREF = "print.html">print</A> or
<A HREF = "if.html">if</A> commands for examples. A "#" or "$" character that is
between quotes will not be treated as a comment indicator in (2) or
substituted for as a variable in (3).
<P>See the <A HREF = "dump_modify.html">dump modify format</A>, <A HREF = "print.html">print</A>,
<A HREF = "if.html">if</A>, and <A HREF = "python.html">python</A> commands for examples.
</P>
<P>A "#" or "$" character that is between quotes will not be treated as a
comment indicator in (2) or substituted for as a variable in (3).
</P>
<P>IMPORTANT NOTE: If the argument is itself a command that requires a
quoted argument (e.g. using a <A HREF = "print.html">print</A> command as part of an
<A HREF = "if.html">if</A> or <A HREF = "run.html">run every</A> command), then the double and
single quotes can be nested in the usual manner. See the doc pages
<A HREF = "if.html">if</A> or <A HREF = "run.html">run every</A> command), then single, double, or
triple quotes can be nested in the usual manner. See the doc pages
for those commands for examples. Only one of level of nesting is
allowed, but that should be sufficient for most use cases.
</P>
@ -407,12 +419,12 @@ g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.
<TR ALIGN="center"><TD ><A HREF = "fix_nh.html">npt (co)</A></TD><TD ><A HREF = "fix_npt_asphere.html">npt/asphere (o)</A></TD><TD ><A HREF = "fix_npt_sphere.html">npt/sphere (o)</A></TD><TD ><A HREF = "fix_nve.html">nve (cko)</A></TD><TD ><A HREF = "fix_nve_asphere.html">nve/asphere</A></TD><TD ><A HREF = "fix_nve_asphere_noforce.html">nve/asphere/noforce</A></TD><TD ><A HREF = "fix_nve_body.html">nve/body</A></TD><TD ><A HREF = "fix_nve_limit.html">nve/limit</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_nve_line.html">nve/line</A></TD><TD ><A HREF = "fix_nve_noforce.html">nve/noforce</A></TD><TD ><A HREF = "fix_nve_sphere.html">nve/sphere (o)</A></TD><TD ><A HREF = "fix_nve_tri.html">nve/tri</A></TD><TD ><A HREF = "fix_nh.html">nvt (co)</A></TD><TD ><A HREF = "fix_nvt_asphere.html">nvt/asphere (o)</A></TD><TD ><A HREF = "fix_nvt_sllod.html">nvt/sllod (o)</A></TD><TD ><A HREF = "fix_nvt_sphere.html">nvt/sphere (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_oneway.html">oneway</A></TD><TD ><A HREF = "fix_orient_fcc.html">orient/fcc</A></TD><TD ><A HREF = "fix_planeforce.html">planeforce</A></TD><TD ><A HREF = "fix_poems.html">poems</A></TD><TD ><A HREF = "fix_pour.html">pour</A></TD><TD ><A HREF = "fix_press_berendsen.html">press/berendsen</A></TD><TD ><A HREF = "fix_print.html">print</A></TD><TD ><A HREF = "fix_property_atom.html">property/atom</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_qeq_comb.html">qeq/comb (o)</A></TD><TD ><A HREF = "fix_qeq.html">qeq/dynamic</A></TD><TD ><A HREF = "fix_qeq.html">qeq/point</A></TD><TD ><A HREF = "fix_qeq.html">qeq/shielded</A></TD><TD ><A HREF = "fix_qeq.html">qeq/slater</A></TD><TD ><A HREF = "fix_shake.html">rattle</A></TD><TD ><A HREF = "fix_reax_bonds.html">reax/bonds</A></TD><TD ><A HREF = "fix_recenter.html">recenter</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_restrain.html">restrain</A></TD><TD ><A HREF = "fix_rigid.html">rigid (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/nph (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/npt (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/nve (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/nvt (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/nph</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_rigid.html">rigid/small/npt</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/nve</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/nvt</A></TD><TD ><A HREF = "fix_setforce.html">setforce (c)</A></TD><TD ><A HREF = "fix_shake.html">shake (c)</A></TD><TD ><A HREF = "fix_spring.html">spring</A></TD><TD ><A HREF = "fix_spring_rg.html">spring/rg</A></TD><TD ><A HREF = "fix_spring_self.html">spring/self</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_srd.html">srd</A></TD><TD ><A HREF = "fix_store_force.html">store/force</A></TD><TD ><A HREF = "fix_store_state.html">store/state</A></TD><TD ><A HREF = "fix_temp_berendsen.html">temp/berendsen (c)</A></TD><TD ><A HREF = "fix_temp_csvr.html">temp/csvr</A></TD><TD ><A HREF = "fix_temp_rescale.html">temp/rescale (c)</A></TD><TD ><A HREF = "fix_tfmc.html">tfmc</A></TD><TD ><A HREF = "fix_thermal_conductivity.html">thermal/conductivity</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_tmd.html">tmd</A></TD><TD ><A HREF = "fix_ttm.html">ttm</A></TD><TD ><A HREF = "fix_tune_kspace.html">tune/kspace</A></TD><TD ><A HREF = "fix_vector.html">vector</A></TD><TD ><A HREF = "fix_viscosity.html">viscosity</A></TD><TD ><A HREF = "fix_viscous.html">viscous (c)</A></TD><TD ><A HREF = "fix_wall.html">wall/colloid</A></TD><TD ><A HREF = "fix_wall_gran.html">wall/gran</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_wall.html">wall/harmonic</A></TD><TD ><A HREF = "fix_wall.html">wall/lj1043</A></TD><TD ><A HREF = "fix_wall.html">wall/lj126</A></TD><TD ><A HREF = "fix_wall.html">wall/lj93</A></TD><TD ><A HREF = "fix_wall_piston.html">wall/piston</A></TD><TD ><A HREF = "fix_wall_reflect.html">wall/reflect</A></TD><TD ><A HREF = "fix_wall_region.html">wall/region</A></TD><TD ><A HREF = "fix_wall_srd.html">wall/srd</A>
<TR ALIGN="center"><TD ><A HREF = "fix_qeq_comb.html">qeq/comb (o)</A></TD><TD ><A HREF = "fix_qeq.html">qeq/dynamic</A></TD><TD ><A HREF = "fix_qeq.html">qeq/point</A></TD><TD ><A HREF = "fix_qeq.html">qeq/shielded</A></TD><TD ><A HREF = "fix_qeq.html">qeq/slater</A></TD><TD ><A HREF = "fix_reax_bonds.html">reax/bonds</A></TD><TD ><A HREF = "fix_recenter.html">recenter</A></TD><TD ><A HREF = "fix_restrain.html">restrain</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_rigid.html">rigid (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/nph (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/npt (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/nve (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/nvt (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/nph</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/npt</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_rigid.html">rigid/small/nve</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/nvt</A></TD><TD ><A HREF = "fix_setforce.html">setforce (c)</A></TD><TD ><A HREF = "fix_shake.html">shake (c)</A></TD><TD ><A HREF = "fix_spring.html">spring</A></TD><TD ><A HREF = "fix_spring_rg.html">spring/rg</A></TD><TD ><A HREF = "fix_spring_self.html">spring/self</A></TD><TD ><A HREF = "fix_srd.html">srd</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_store_force.html">store/force</A></TD><TD ><A HREF = "fix_store_state.html">store/state</A></TD><TD ><A HREF = "fix_temp_berendsen.html">temp/berendsen (c)</A></TD><TD ><A HREF = "fix_temp_csvr.html">temp/csvr</A></TD><TD ><A HREF = "fix_temp_rescale.html">temp/rescale (c)</A></TD><TD ><A HREF = "fix_tfmc.html">tfmc</A></TD><TD ><A HREF = "fix_thermal_conductivity.html">thermal/conductivity</A></TD><TD ><A HREF = "fix_tmd.html">tmd</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_ttm.html">ttm</A></TD><TD ><A HREF = "fix_tune_kspace.html">tune/kspace</A></TD><TD ><A HREF = "fix_vector.html">vector</A></TD><TD ><A HREF = "fix_viscosity.html">viscosity</A></TD><TD ><A HREF = "fix_viscous.html">viscous (c)</A></TD><TD ><A HREF = "fix_wall.html">wall/colloid</A></TD><TD ><A HREF = "fix_wall_gran.html">wall/gran</A></TD><TD ><A HREF = "fix_wall.html">wall/harmonic</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "fix_wall.html">wall/lj1043</A></TD><TD ><A HREF = "fix_wall.html">wall/lj126</A></TD><TD ><A HREF = "fix_wall.html">wall/lj93</A></TD><TD ><A HREF = "fix_wall_piston.html">wall/piston</A></TD><TD ><A HREF = "fix_wall_reflect.html">wall/reflect</A></TD><TD ><A HREF = "fix_wall_region.html">wall/region</A></TD><TD ><A HREF = "fix_wall_srd.html">wall/srd</A>
</TD></TR></TABLE></DIV>
<P>These are additional fix styles in USER packages, which can be used if
@ -449,9 +461,9 @@ KOKKOS, o = USER-OMP, t = OPT.
<TR ALIGN="center"><TD ><A HREF = "compute_msd_chunk.html">msd/chunk</A></TD><TD ><A HREF = "compute_msd_nongauss.html">msd/nongauss</A></TD><TD ><A HREF = "compute_pair.html">pair</A></TD><TD ><A HREF = "compute_pair_local.html">pair/local</A></TD><TD ><A HREF = "compute_pe.html">pe (c)</A></TD><TD ><A HREF = "compute_pe_atom.html">pe/atom</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "compute_plasticity_atom.html">plasticity/atom</A></TD><TD ><A HREF = "compute_pressure.html">pressure (c)</A></TD><TD ><A HREF = "compute_property_atom.html">property/atom</A></TD><TD ><A HREF = "compute_property_local.html">property/local</A></TD><TD ><A HREF = "compute_property_chunk.html">property/chunk</A></TD><TD ><A HREF = "compute_rdf.html">rdf</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "compute_reduce.html">reduce</A></TD><TD ><A HREF = "compute_reduce.html">reduce/region</A></TD><TD ><A HREF = "compute_slice.html">slice</A></TD><TD ><A HREF = "compute_sna.html">sna/atom</A></TD><TD ><A HREF = "compute_sna.html">snad/atom</A></TD><TD ><A HREF = "compute_sna.html">snav/atom</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "compute_stress_atom.html">stress/atom</A></TD><TD ><A HREF = "compute_temp.html">temp (c)</A></TD><TD ><A HREF = "compute_temp_asphere.html">temp/asphere</A></TD><TD ><A HREF = "compute_temp_com.html">temp/com</A></TD><TD ><A HREF = "compute_temp_chunk.html">temp/chunk</A></TD><TD ><A HREF = "compute_temp_cs.html">temp/cs</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "compute_temp_deform.html">temp/deform</A></TD><TD ><A HREF = "compute_temp_partial.html">temp/partial (c)</A></TD><TD ><A HREF = "compute_temp_profile.html">temp/profile</A></TD><TD ><A HREF = "compute_temp_ramp.html">temp/ramp</A></TD><TD ><A HREF = "compute_temp_region.html">temp/region</A></TD><TD ><A HREF = "compute_temp_sphere.html">temp/sphere</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "compute_ti.html">ti</A></TD><TD ><A HREF = "compute_torque_chunk.html">torque/chunk</A></TD><TD ><A HREF = "compute_vacf.html">vacf</A></TD><TD ><A HREF = "compute_vcm_chunk.html">vcm/chunk</A></TD><TD ><A HREF = "compute_voronoi_atom.html">voronoi/atom</A>
<TR ALIGN="center"><TD ><A HREF = "compute_stress_atom.html">stress/atom</A></TD><TD ><A HREF = "compute_temp.html">temp (c)</A></TD><TD ><A HREF = "compute_temp_asphere.html">temp/asphere</A></TD><TD ><A HREF = "compute_temp_com.html">temp/com</A></TD><TD ><A HREF = "compute_temp_chunk.html">temp/chunk</A></TD><TD ><A HREF = "compute_temp_deform.html">temp/deform</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "compute_temp_partial.html">temp/partial (c)</A></TD><TD ><A HREF = "compute_temp_profile.html">temp/profile</A></TD><TD ><A HREF = "compute_temp_ramp.html">temp/ramp</A></TD><TD ><A HREF = "compute_temp_region.html">temp/region</A></TD><TD ><A HREF = "compute_temp_sphere.html">temp/sphere</A></TD><TD ><A HREF = "compute_ti.html">ti</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "compute_torque_chunk.html">torque/chunk</A></TD><TD ><A HREF = "compute_vacf.html">vacf</A></TD><TD ><A HREF = "compute_vcm_chunk.html">vcm/chunk</A></TD><TD ><A HREF = "compute_voronoi_atom.html">voronoi/atom</A>
</TD></TR></TABLE></DIV>
<P>These are additional compute styles in USER packages, which can be
@ -478,31 +490,30 @@ KOKKOS, o = USER-OMP, t = OPT.
<DIV ALIGN=center><TABLE BORDER=1 >
<TR ALIGN="center"><TD ><A HREF = "pair_none.html">none</A></TD><TD ><A HREF = "pair_hybrid.html">hybrid</A></TD><TD ><A HREF = "pair_hybrid.html">hybrid/overlay</A></TD><TD ><A HREF = "pair_adp.html">adp (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_airebo.html">airebo (o)</A></TD><TD ><A HREF = "pair_beck.html">beck (go)</A></TD><TD ><A HREF = "pair_body.html">body</A></TD><TD ><A HREF = "pair_bop.html">bop</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_born.html">born (go)</A></TD><TD ><A HREF = "pair_born.html">born/coul/long (cgo)</A></TD><TD ><A HREF = "pair_cs.html">born/coul/long/cs</A></TD><TD ><A HREF = "pair_born.html">born/coul/msm (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_born.html">born/coul/wolf (go)</A></TD><TD ><A HREF = "pair_brownian.html">brownian (o)</A></TD><TD ><A HREF = "pair_brownian.html">brownian/poly (o)</A></TD><TD ><A HREF = "pair_buck.html">buck (cgko)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_buck.html">buck/coul/cut (cgo)</A></TD><TD ><A HREF = "pair_buck.html">buck/coul/long (cgo)</A></TD><TD ><A HREF = "pair_cs.html">buck/coul/long/cs</A></TD><TD ><A HREF = "pair_buck.html">buck/coul/msm (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_buck_long.html">buck/long/coul/long (o)</A></TD><TD ><A HREF = "pair_colloid.html">colloid (go)</A></TD><TD ><A HREF = "pair_comb.html">comb (o)</A></TD><TD ><A HREF = "pair_comb.html">comb3</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_coul.html">coul/cut (gko)</A></TD><TD ><A HREF = "pair_coul.html">coul/debye (go)</A></TD><TD ><A HREF = "pair_coul.html">coul/dsf (gko)</A></TD><TD ><A HREF = "pair_coul.html">coul/long (go)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_coul.html">coul/msm</A></TD><TD ><A HREF = "pair_coul.html">coul/streitz</A></TD><TD ><A HREF = "pair_coul.html">coul/wolf (ko)</A></TD><TD ><A HREF = "pair_dpd.html">dpd (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_dpd.html">dpd/tstat (o)</A></TD><TD ><A HREF = "pair_dsmc.html">dsmc</A></TD><TD ><A HREF = "pair_eam.html">eam (cgkot)</A></TD><TD ><A HREF = "pair_eam.html">eam/alloy (cgot)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_eam.html">eam/fs (cgot)</A></TD><TD ><A HREF = "pair_eim.html">eim (o)</A></TD><TD ><A HREF = "pair_gauss.html">gauss (go)</A></TD><TD ><A HREF = "pair_gayberne.html">gayberne (gio)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_gran.html">gran/hertz/history (o)</A></TD><TD ><A HREF = "pair_gran.html">gran/hooke (co)</A></TD><TD ><A HREF = "pair_gran.html">gran/hooke/history (o)</A></TD><TD ><A HREF = "pair_hbond_dreiding.html">hbond/dreiding/lj (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_hbond_dreiding.html">hbond/dreiding/morse (o)</A></TD><TD ><A HREF = "pair_kim.html">kim</A></TD><TD ><A HREF = "pair_lcbop.html">lcbop</A></TD><TD ><A HREF = "pair_line_lj.html">line/lj (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_charmm.html">lj/charmm/coul/charmm (co)</A></TD><TD ><A HREF = "pair_charmm.html">lj/charmm/coul/charmm/implicit (co)</A></TD><TD ><A HREF = "pair_charmm.html">lj/charmm/coul/long (cgio)</A></TD><TD ><A HREF = "pair_charmm.html">lj/charmm/coul/msm</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_class2.html">lj/class2 (cgo)</A></TD><TD ><A HREF = "pair_class2.html">lj/class2/coul/cut (co)</A></TD><TD ><A HREF = "pair_class2.html">lj/class2/coul/long (cgo)</A></TD><TD ><A HREF = "pair_lj.html">lj/cut (cgikot)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_lj.html">lj/cut/coul/cut (cgko)</A></TD><TD ><A HREF = "pair_lj.html">lj/cut/coul/debye (cgo)</A></TD><TD ><A HREF = "pair_lj.html">lj/cut/coul/dsf (go)</A></TD><TD ><A HREF = "pair_lj.html">lj/cut/coul/long (cgikot)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_lj.html">lj/cut/coul/msm (go)</A></TD><TD ><A HREF = "pair_dipole.html">lj/cut/dipole/cut (go)</A></TD><TD ><A HREF = "pair_dipole.html">lj/cut/dipole/long</A></TD><TD ><A HREF = "pair_lj.html">lj/cut/tip4p/cut (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_lj.html">lj/cut/tip4p/long (ot)</A></TD><TD ><A HREF = "pair_lj_expand.html">lj/expand (cgo)</A></TD><TD ><A HREF = "pair_gromacs.html">lj/gromacs (cgo)</A></TD><TD ><A HREF = "pair_gromacs.html">lj/gromacs/coul/gromacs (co)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_lj_long.html">lj/long/coul/long (o)</A></TD><TD ><A HREF = "pair_dipole.html">lj/long/dipole/long</A></TD><TD ><A HREF = "pair_lj_long.html">lj/long/tip4p/long</A></TD><TD ><A HREF = "pair_lj_smooth.html">lj/smooth (co)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_lj_smooth_linear.html">lj/smooth/linear (o)</A></TD><TD ><A HREF = "pair_lj96.html">lj96/cut (cgo)</A></TD><TD ><A HREF = "pair_lubricate.html">lubricate (o)</A></TD><TD ><A HREF = "pair_lubricate.html">lubricate/poly (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_lubricateU.html">lubricateU</A></TD><TD ><A HREF = "pair_lubricateU.html">lubricateU/poly</A></TD><TD ><A HREF = "pair_meam.html">meam (o)</A></TD><TD ><A HREF = "pair_mie.html">mie/cut (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_morse.html">morse (cgot)</A></TD><TD ><A HREF = "pair_nb3b_harmonic.html">nb3b/harmonic (o)</A></TD><TD ><A HREF = "pair_nm.html">nm/cut (o)</A></TD><TD ><A HREF = "pair_nm.html">nm/cut/coul/cut (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_nm.html">nm/cut/coul/long (o)</A></TD><TD ><A HREF = "pair_peri.html">peri/eps</A></TD><TD ><A HREF = "pair_peri.html">peri/lps (o)</A></TD><TD ><A HREF = "pair_peri.html">peri/pmb (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_peri.html">peri/ves</A></TD><TD ><A HREF = "pair_reax.html">reax</A></TD><TD ><A HREF = "pair_airebo.html">rebo (o)</A></TD><TD ><A HREF = "pair_resquared.html">resquared (go)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_snap.html">snap</A></TD><TD ><A HREF = "pair_soft.html">soft (go)</A></TD><TD ><A HREF = "pair_sw.html">sw (cgio)</A></TD><TD ><A HREF = "pair_table.html">table (gko)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_tersoff.html">tersoff (co)</A></TD><TD ><A HREF = "pair_tersoff_mod.html">tersoff/mod (o)</A></TD><TD ><A HREF = "pair_tersoff_zbl.html">tersoff/zbl (o)</A></TD><TD ><A HREF = "pair_coul.html">tip4p/cut (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_coul.html">tip4p/long (o)</A></TD><TD ><A HREF = "pair_tri_lj.html">tri/lj (o)</A></TD><TD ><A HREF = "pair_yukawa.html">yukawa (go)</A></TD><TD ><A HREF = "pair_yukawa_colloid.html">yukawa/colloid (go)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_zbl.html">zbl (o)</A>
<TR ALIGN="center"><TD ><A HREF = "pair_born.html">born (go)</A></TD><TD ><A HREF = "pair_born.html">born/coul/long (cgo)</A></TD><TD ><A HREF = "pair_born.html">born/coul/msm (o)</A></TD><TD ><A HREF = "pair_born.html">born/coul/wolf (go)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_brownian.html">brownian (o)</A></TD><TD ><A HREF = "pair_brownian.html">brownian/poly (o)</A></TD><TD ><A HREF = "pair_buck.html">buck (cgko)</A></TD><TD ><A HREF = "pair_buck.html">buck/coul/cut (cgo)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_buck.html">buck/coul/long (cgo)</A></TD><TD ><A HREF = "pair_buck.html">buck/coul/msm (o)</A></TD><TD ><A HREF = "pair_buck_long.html">buck/long/coul/long (o)</A></TD><TD ><A HREF = "pair_colloid.html">colloid (go)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_comb.html">comb (o)</A></TD><TD ><A HREF = "pair_comb.html">comb3</A></TD><TD ><A HREF = "pair_coul.html">coul/cut (gko)</A></TD><TD ><A HREF = "pair_coul.html">coul/debye (go)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_coul.html">coul/dsf (gko)</A></TD><TD ><A HREF = "pair_coul.html">coul/long (go)</A></TD><TD ><A HREF = "pair_coul.html">coul/msm</A></TD><TD ><A HREF = "pair_coul.html">coul/streitz</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_coul.html">coul/wolf (ko)</A></TD><TD ><A HREF = "pair_dpd.html">dpd (o)</A></TD><TD ><A HREF = "pair_dpd.html">dpd/tstat (o)</A></TD><TD ><A HREF = "pair_dsmc.html">dsmc</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_eam.html">eam (cgkot)</A></TD><TD ><A HREF = "pair_eam.html">eam/alloy (cgot)</A></TD><TD ><A HREF = "pair_eam.html">eam/fs (cgot)</A></TD><TD ><A HREF = "pair_eim.html">eim (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_gauss.html">gauss (go)</A></TD><TD ><A HREF = "pair_gayberne.html">gayberne (gio)</A></TD><TD ><A HREF = "pair_gran.html">gran/hertz/history (o)</A></TD><TD ><A HREF = "pair_gran.html">gran/hooke (co)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_gran.html">gran/hooke/history (o)</A></TD><TD ><A HREF = "pair_hbond_dreiding.html">hbond/dreiding/lj (o)</A></TD><TD ><A HREF = "pair_hbond_dreiding.html">hbond/dreiding/morse (o)</A></TD><TD ><A HREF = "pair_kim.html">kim</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_lcbop.html">lcbop</A></TD><TD ><A HREF = "pair_line_lj.html">line/lj (o)</A></TD><TD ><A HREF = "pair_charmm.html">lj/charmm/coul/charmm (co)</A></TD><TD ><A HREF = "pair_charmm.html">lj/charmm/coul/charmm/implicit (co)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_charmm.html">lj/charmm/coul/long (cgio)</A></TD><TD ><A HREF = "pair_charmm.html">lj/charmm/coul/msm</A></TD><TD ><A HREF = "pair_class2.html">lj/class2 (cgo)</A></TD><TD ><A HREF = "pair_class2.html">lj/class2/coul/cut (co)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_class2.html">lj/class2/coul/long (cgo)</A></TD><TD ><A HREF = "pair_lj.html">lj/cut (cgikot)</A></TD><TD ><A HREF = "pair_lj.html">lj/cut/coul/cut (cgko)</A></TD><TD ><A HREF = "pair_lj.html">lj/cut/coul/debye (cgo)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_lj.html">lj/cut/coul/dsf (go)</A></TD><TD ><A HREF = "pair_lj.html">lj/cut/coul/long (cgikot)</A></TD><TD ><A HREF = "pair_lj.html">lj/cut/coul/msm (go)</A></TD><TD ><A HREF = "pair_dipole.html">lj/cut/dipole/cut (go)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_dipole.html">lj/cut/dipole/long</A></TD><TD ><A HREF = "pair_lj.html">lj/cut/tip4p/cut (o)</A></TD><TD ><A HREF = "pair_lj.html">lj/cut/tip4p/long (ot)</A></TD><TD ><A HREF = "pair_lj_expand.html">lj/expand (cgo)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_gromacs.html">lj/gromacs (cgo)</A></TD><TD ><A HREF = "pair_gromacs.html">lj/gromacs/coul/gromacs (co)</A></TD><TD ><A HREF = "pair_lj_long.html">lj/long/coul/long (o)</A></TD><TD ><A HREF = "pair_dipole.html">lj/long/dipole/long</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_lj_long.html">lj/long/tip4p/long</A></TD><TD ><A HREF = "pair_lj_smooth.html">lj/smooth (co)</A></TD><TD ><A HREF = "pair_lj_smooth_linear.html">lj/smooth/linear (o)</A></TD><TD ><A HREF = "pair_lj96.html">lj96/cut (cgo)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_lubricate.html">lubricate (o)</A></TD><TD ><A HREF = "pair_lubricate.html">lubricate/poly (o)</A></TD><TD ><A HREF = "pair_lubricateU.html">lubricateU</A></TD><TD ><A HREF = "pair_lubricateU.html">lubricateU/poly</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_meam.html">meam (o)</A></TD><TD ><A HREF = "pair_mie.html">mie/cut (o)</A></TD><TD ><A HREF = "pair_morse.html">morse (cgot)</A></TD><TD ><A HREF = "pair_nb3b_harmonic.html">nb3b/harmonic (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_nm.html">nm/cut (o)</A></TD><TD ><A HREF = "pair_nm.html">nm/cut/coul/cut (o)</A></TD><TD ><A HREF = "pair_nm.html">nm/cut/coul/long (o)</A></TD><TD ><A HREF = "pair_peri.html">peri/eps</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_peri.html">peri/lps (o)</A></TD><TD ><A HREF = "pair_peri.html">peri/pmb (o)</A></TD><TD ><A HREF = "pair_peri.html">peri/ves</A></TD><TD ><A HREF = "pair_reax.html">reax</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_airebo.html">rebo (o)</A></TD><TD ><A HREF = "pair_resquared.html">resquared (go)</A></TD><TD ><A HREF = "pair_snap.html">snap</A></TD><TD ><A HREF = "pair_soft.html">soft (go)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_sw.html">sw (cgo)</A></TD><TD ><A HREF = "pair_table.html">table (gko)</A></TD><TD ><A HREF = "pair_tersoff.html">tersoff (co)</A></TD><TD ><A HREF = "pair_tersoff_mod.html">tersoff/mod (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_tersoff_zbl.html">tersoff/zbl (o)</A></TD><TD ><A HREF = "pair_coul.html">tip4p/cut (o)</A></TD><TD ><A HREF = "pair_coul.html">tip4p/long (o)</A></TD><TD ><A HREF = "pair_tri_lj.html">tri/lj (o)</A></TD></TR>
<TR ALIGN="center"><TD ><A HREF = "pair_yukawa.html">yukawa (go)</A></TD><TD ><A HREF = "pair_yukawa_colloid.html">yukawa/colloid (go)</A></TD><TD ><A HREF = "pair_zbl.html">zbl (o)</A>
</TD></TR></TABLE></DIV>
<P>These are additional pair styles in USER packages, which can be used

56
doc/Section_commands.txt
View File

@ -82,11 +82,12 @@ file names or user-chosen ID strings.
Here is how each line in the input script is parsed by LAMMPS:
(1) If the last printable character on the line is a "&" character
(with no surrounding quotes), the command is assumed to continue on
the next line. The next line is concatenated to the previous line by
removing the "&" character and newline. This allows long commands to
be continued across two or more lines.
(1) If the last printable character on the line is a "&" character,
the command is assumed to continue on the next line. The next line is
concatenated to the previous line by removing the "&" character and
line break. This allows long commands to be continued across two or
more lines. See the discussion of triple quotes in (6) for how to
continue a command across multiple line without using "&" characters.
(2) All characters from the first "#" character onward are treated as
comment and discarded. See an exception in (6). Note that a
@ -132,9 +133,9 @@ Note that neither the curly-bracket or immediate form of variables can
contain nested $ characters for other variables to substitute for.
Thus you cannot do this:
variable a equal 2
variable b2 equal 4
region 1 block $\{b$a\} 2 INF INF EDGE EDGE :pre
variable a equal 2
variable b2 equal 4
print "B2 = $\{b$a\}" :pre
Nor can you specify this $($x-1.0) for an immediate variable, but
you could use $(v_x-1.0), since the latter is valid syntax for an
@ -152,27 +153,38 @@ underscores, or punctuation characters.
line are arguments.
(6) If you want text with spaces to be treated as a single argument,
it can be enclosed in either double or single quotes. A long single
argument enclosed in quotes can even span multiple lines if the "&"
character is used, as described above. E.g.
it can be enclosed in either single or double or triple quotes. A
long single argument enclosed in single or double quotes can span
multiple lines if the "&" character is used, as described above. When
the lines are concatenated together (and the "&" characters and line
breaks removed), the text will become a single line. If you want
multiple lines of an argument to retain their line breaks, the text
can be enclosed in triple quotes, in which case "&" characters are not
needed. For example:
print "Volume = $v"
print 'Volume = $v'
if "${steps} > 1000" then quit
variable a string "red green blue &
purple orange cyan"
if "${steps} > 1000" then quit :pre
print """
System volume = $v
System temperature = $t
""" :pre
The quotes are removed when the single argument is stored internally.
In each case, the single, double, or triple quotes are removed when
the single argument they enclose is stored internally.
See the "dump modify format"_dump_modify.html or "print"_print.html or
"if"_if.html commands for examples. A "#" or "$" character that is
between quotes will not be treated as a comment indicator in (2) or
substituted for as a variable in (3).
See the "dump modify format"_dump_modify.html, "print"_print.html,
"if"_if.html, and "python"_python.html commands for examples.
A "#" or "$" character that is between quotes will not be treated as a
comment indicator in (2) or substituted for as a variable in (3).
IMPORTANT NOTE: If the argument is itself a command that requires a
quoted argument (e.g. using a "print"_print.html command as part of an
"if"_if.html or "run every"_run.html command), then the double and
single quotes can be nested in the usual manner. See the doc pages
"if"_if.html or "run every"_run.html command), then single, double, or
triple quotes can be nested in the usual manner. See the doc pages
for those commands for examples. Only one of level of nesting is
allowed, but that should be sufficient for most use cases.
@ -535,7 +547,6 @@ g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.
"qeq/point"_fix_qeq.html,
"qeq/shielded"_fix_qeq.html,
"qeq/slater"_fix_qeq.html,
"rattle"_fix_shake.html,
"reax/bonds"_fix_reax_bonds.html,
"recenter"_fix_recenter.html,
"restrain"_fix_restrain.html,
@ -681,7 +692,6 @@ KOKKOS, o = USER-OMP, t = OPT.
"temp/asphere"_compute_temp_asphere.html,
"temp/com"_compute_temp_com.html,
"temp/chunk"_compute_temp_chunk.html,
"temp/cs"_compute_temp_cs.html,
"temp/deform"_compute_temp_deform.html,
"temp/partial (c)"_compute_temp_partial.html,
"temp/profile"_compute_temp_profile.html,
@ -733,7 +743,6 @@ KOKKOS, o = USER-OMP, t = OPT.
"bop"_pair_bop.html,
"born (go)"_pair_born.html,
"born/coul/long (cgo)"_pair_born.html,
"born/coul/long/cs"_pair_cs.html,
"born/coul/msm (o)"_pair_born.html,
"born/coul/wolf (go)"_pair_born.html,
"brownian (o)"_pair_brownian.html,
@ -741,7 +750,6 @@ KOKKOS, o = USER-OMP, t = OPT.
"buck (cgko)"_pair_buck.html,
"buck/coul/cut (cgo)"_pair_buck.html,
"buck/coul/long (cgo)"_pair_buck.html,
"buck/coul/long/cs"_pair_cs.html,
"buck/coul/msm (o)"_pair_buck.html,
"buck/long/coul/long (o)"_pair_buck_long.html,
"colloid (go)"_pair_colloid.html,
@ -817,7 +825,7 @@ KOKKOS, o = USER-OMP, t = OPT.
"resquared (go)"_pair_resquared.html,
"snap"_pair_snap.html,
"soft (go)"_pair_soft.html,
"sw (cgio)"_pair_sw.html,
"sw (cgo)"_pair_sw.html,
"table (gko)"_pair_table.html,
"tersoff (co)"_pair_tersoff.html,
"tersoff/mod (o)"_pair_tersoff_mod.html,

1
doc/Section_packages.html
View File

@ -63,6 +63,7 @@ packages, more details are provided.
<TR ALIGN="center"><TD >OPT</TD><TD > optimized pair styles</TD><TD > Fischer & Richie & Natoli (2)</TD><TD > <A HREF = "accelerate_opt.html">Section accelerate</A></TD><TD > -</TD><TD > -</TD></TR>
<TR ALIGN="center"><TD >PERI</TD><TD > Peridynamics models</TD><TD > Mike Parks (Sandia)</TD><TD > <A HREF = "pair_peri.html">pair_style peri</A></TD><TD > peri</TD><TD > -</TD></TR>
<TR ALIGN="center"><TD >POEMS</TD><TD > coupled rigid body motion</TD><TD > Rudra Mukherjee (JPL)</TD><TD > <A HREF = "fix_poems.html">fix poems</A></TD><TD > rigid</TD><TD > lib/poems</TD></TR>
<TR ALIGN="center"><TD >PYTHON</TD><TD > embed Python code in an input script</TD><TD > -</TD><TD > <A HREF = "python.html">python</A></TD><TD > python</TD><TD > lib/python</TD></TR>
<TR ALIGN="center"><TD >REAX</TD><TD > ReaxFF potential</TD><TD > Aidan Thompson (Sandia)</TD><TD > <A HREF = "pair_reax.html">pair_style reax</A></TD><TD > reax</TD><TD > lib/reax</TD></TR>
<TR ALIGN="center"><TD >REPLICA</TD><TD > multi-replica methods</TD><TD > -</TD><TD > <A HREF = "Section_howto.html#howto_5">Section_howto 6.5</A></TD><TD > tad</TD><TD > -</TD></TR>
<TR ALIGN="center"><TD >RIGID</TD><TD > rigid bodies</TD><TD > -</TD><TD > <A HREF = "fix_rigid.html">fix rigid</A></TD><TD > rigid</TD><TD > -</TD></TR>

1
doc/Section_packages.txt
View File

@ -58,6 +58,7 @@ MOLECULE, molecular system force fields, -, "Section_howto 6.3"_Section_howto.ht
OPT, optimized pair styles, Fischer & Richie & Natoli (2), "Section accelerate"_accelerate_opt.html, -, -
PERI, Peridynamics models, Mike Parks (Sandia), "pair_style peri"_pair_peri.html, peri, -
POEMS, coupled rigid body motion, Rudra Mukherjee (JPL), "fix poems"_fix_poems.html, rigid, lib/poems
PYTHON, embed Python code in an input script, -, "python"_python.html, python, lib/python
REAX, ReaxFF potential, Aidan Thompson (Sandia), "pair_style reax"_pair_reax.html, reax, lib/reax
REPLICA, multi-replica methods, -, "Section_howto 6.5"_Section_howto.html#howto_5, tad, -
RIGID, rigid bodies, -, "fix rigid"_fix_rigid.html, rigid, -

268
doc/Section_python.html
View File

@ -11,61 +11,98 @@
<H3>11. Python interface to LAMMPS
</H3>
<P>This section describes how to build and use LAMMPS via a Python
interface.
<P>LAMMPS can work together with Python in two ways. First, Python can
wrap LAMMPS through the <A HREF = "Section_howto.html#howto_19">LAMMPS library
interface</A>, so that a Python script can
create one or more instances of LAMMPS and launch one or more
simulations. In Python lingo, this is "extending" Python with LAMMPS.
</P>
<UL><LI>11.1 <A HREF = "#py_1">Building LAMMPS as a shared library</A>
<LI>11.2 <A HREF = "#py_2">Installing the Python wrapper into Python</A>
<LI>11.3 <A HREF = "#py_3">Extending Python with MPI to run in parallel</A>
<LI>11.4 <A HREF = "#py_4">Testing the Python-LAMMPS interface</A>
<LI>11.5 <A HREF = "#py_5">Using LAMMPS from Python</A>
<LI>11.6 <A HREF = "#py_6">Example Python scripts that use LAMMPS</A>
<P>Second, LAMMPS can use the Python interpreter, so that a LAMMPS input
script can invoke Python code, and pass information back-and-forth
between the input script and Python functions you write. The Python
code can also callback to LAMMPS to query or change its attributes.
In Python lingo, this is "embedding" Python in LAMMPS.
</P>
<P>This section describes how to do both.
</P>
<UL><LI>11.1 <A HREF = "#py_1">Overview of running LAMMPS from Python</A>
<LI>11.2 <A HREF = "#py_2">Overview of using Python from a LAMMPS script</A>
<LI>11.3 <A HREF = "#py_3">Building LAMMPS as a shared library</A>
<LI>11.4 <A HREF = "#py_4">Installing the Python wrapper into Python</A>
<LI>11.5 <A HREF = "#py_5">Extending Python with MPI to run in parallel</A>
<LI>11.6 <A HREF = "#py_6">Testing the Python-LAMMPS interface</A>
<LI>11.7 <A HREF = "#py_7">Using LAMMPS from Python</A>
<LI>11.8 <A HREF = "#py_8">Example Python scripts that use LAMMPS</A>
</UL>
<P>The LAMMPS distribution includes the file python/lammps.py which wraps
the library interface to LAMMPS. This file makes it is possible to
run LAMMPS, invoke LAMMPS commands or give it an input script, extract
LAMMPS results, an modify internal LAMMPS variables, either from a
Python script or interactively from a Python prompt. You can do the
former in serial or parallel. Running Python interactively in
parallel does not generally work, unless you have a package installed
that extends your Python to enable multiple instances of Python to
read what you type.
<P>If you are not familiar with it, <A HREF = "http://www.python.org">Python</A> is a
powerful scripting and programming language which can essentially do
anything that faster, lower-level languages like C or C++ can do, but
typically with much fewer lines of code. When used in embedded mode,
Python can perform operations that the simplistic LAMMPS input script
syntax cannot. Python can be also be used as a "glue" language to
drive a program through its library interface, or to hook multiple
pieces of software together, such as a simulation package plus a
visualization package, or to run a coupled multiscale or multiphysics
model.
</P>
<P><A HREF = "http://www.python.org">Python</A> is a powerful scripting and programming
language which can be used to wrap software like LAMMPS and other
packages. It can be used to glue multiple pieces of software
together, e.g. to run a coupled or multiscale model. See <A HREF = "Section_howto.html#howto_10">Section
section</A> of the manual and the couple
directory of the distribution for more ideas about coupling LAMMPS to
other codes. See <A HREF = "Section_start.html#start_5">Section_start 4</A> about
how to build LAMMPS as a library, and <A HREF = "Section_howto.html#howto_19">Section_howto
19</A> for a description of the library
interface provided in src/library.cpp and src/library.h and how to
extend it for your needs. As described below, that interface is what
is exposed to Python. It is designed to be easy to add functions to.
This can easily extend the Python inteface as well. See details
below.
<P>See <A HREF = "Section_howto.html#howto_10">Section_howto 10</A> of the manual and
the couple directory of the distribution for more ideas about coupling
LAMMPS to other codes. See <A HREF = "Section_howto.html#howto_19">Section_howto
19</A> for a description of the LAMMPS
library interface provided in src/library.cpp and src/library.h, and
how to extend it for your needs. As described below, that interface
is what is exposed to Python either when calling LAMMPS from Python or
when calling Python from a LAMMPS input script and then calling back
to LAMMPS from Python code. The library interface is designed to be
easy to add functions to. Thus the Python interface to LAMMPS is also
easy to extend as well.
</P>
<P>By using the Python interface, LAMMPS can also be coupled with a GUI
or other visualization tools that display graphs or animations in real
time as LAMMPS runs. Examples of such scripts are inlcluded in the
python directory.
<P>If you create interesting Python scripts that run LAMMPS or
interesting Python functions that can be called from a LAMMPS input
script, that you think would be useful to other users, please <A HREF = "http://lammps.sandia.gov/authors.html">email
them to the developers</A>. We can
include them in the LAMMPS distribution.
</P>
<P>Two advantages of using Python are how concise the language is, and
that it can be run interactively, enabling rapid development and
debugging of programs. If you use it to mostly invoke costly
operations within LAMMPS, such as running a simulation for a
<HR>
<HR>
<A NAME = "py_1"></A><H4>11.1 Overview of running LAMMPS from Python
</H4>
<P>The LAMMPS distribution includes a python directory with all you need
to run LAMMPS from Python. The python/lammps.py file wraps the LAMMPS
library interface, with one wrapper function per LAMMPS library
function. This file makes it is possible to do the following either
from a Python script, or interactively from a Python prompt: create
one or more instances of LAMMPS, invoke LAMMPS commands or give it an
input script, run LAMMPS incrementally, extract LAMMPS results, an
modify internal LAMMPS variables. From a Python script you can do
this in serial or parallel. Running Python interactively in parallel
does not generally work, unless you have a version of Python that
extends standard Python to enable multiple instances of Python to read
what you type.
</P>
<P>To do all of this, you must first build LAMMPS as a shared library,
then insure that your Python can find the python/lammps.py file and
the shared library. These steps are explained in subsequent sections
11.3 and 11.4. Sections 11.5 and 11.6 discuss using MPI from a
parallel Python program and how to test that you are ready to use
LAMMPS from Python. Section 11.7 lists all the functions in the
current LAMMPS library interface and how to call them from Python.
</P>
<P>Section 11.8 gives some examples of coupling LAMMPS to other tools via
Python. For example, LAMMPS can easily be coupled to a GUI or other
visualization tools that display graphs or animations in real time as
LAMMPS runs. Examples of such scripts are inlcluded in the python
directory.
</P>
<P>Two advantages of using Python to run LAMMPS are how concise the
language is, and that it can be run interactively, enabling rapid
development and debugging of programs. If you use it to mostly invoke
costly operations within LAMMPS, such as running a simulation for a
reasonable number of timesteps, then the overhead cost of invoking
LAMMPS thru Python will be negligible.
</P>
<P>Before using LAMMPS from a Python script, you need to do two things.
You need to build LAMMPS as a dynamic shared library, so it can be
loaded by Python. And you need to tell Python how to find the library
and the Python wrapper file python/lammps.py. Both these steps are
discussed below. If you wish to run LAMMPS in parallel from Python,
you also need to extend your Python with MPI. This is also discussed
below.
</P>
<P>The Python wrapper for LAMMPS uses the amazing and magical (to me)
"ctypes" package in Python, which auto-generates the interface code
needed between Python and a set of C interface routines for a library.
@ -75,16 +112,77 @@ check which version of Python you have installed, by simply typing
</P>
<HR>
<A NAME = "py_2"></A><H4>11.2 Overview of using Python from a LAMMPS script
</H4>
<P>LAMMPS has a <A HREF = "python.html">python</A> command which can be used in an
input script to define and execute a Python function that you write
the code for. The Python function can also be assigned to a LAMMPS
python-style variable via the <A HREF = "variable.html">variable</A> command. Each
time the variable is evaluated, either in the LAMMPS input script
itself, or by another LAMMPS command that uses the variable, this will
trigger the Python function to be invoked.
</P>
<P>The Python code for the function can be included directly in the input
script or in an auxiliary file. The function can have arguments which
are mapped to LAMMPS variables (also defined in the input script) and
it can return a value to a LAMMPS variable. This is thus a mechanism
for your input script to pass information to a piece of Python code,
ask Python to execute the code, and return information to your input
script.
</P>
<P>Note that a Python function can be arbitrarily complex. It can import
other Python modules, instantiate Python classes, call other Python
functions, etc. The Python code that you provide can contain more
code than the single function. It can contain other functions or
Python classes, as well as global variables or other mechanisms for
storing state between calls from LAMMPS to the function.
</P>
<P>The Python function you provide can consist of "pure" Python code that
only performs operations provided by standard Python. However, the
Python function can also "call back" to LAMMPS through its
Python-wrapped library interface, in the manner described in the
previous section 11.1. This means it can issue LAMMPS input script
commands or query and set internal LAMMPS state. As an example, this
can be useful in an input script to create a more complex loop with
branching logic, than can be created using the simple looping and
brancing logic enabled by the <A HREF = "next_html">next</A> and <A HREF = "if.html">if</A>
commands.
</P>
<P>See the <A HREF = "python.html">python</A> doc page and the <A HREF = "variable.html">variable</A>
doc page for its python-style variables for more info, including
examples of Python code you can write for both pure Python operations
and callbacks to LAMMPS.
</P>
<P>To run pure Python code from LAMMPS, you only need to build LAMMPS
with the PYTHON package installed:
</P>
<P>make yes-python
make machine
</P>
<P>Note that this will link LAMMPS with the Python library on your
system, which typically requires several auxiliary system libraries to
also be linked. The list of these libraries and the paths to find
them are specified in the lib/python/Makefile.lammps file. You need
to insure that file contains the correct information for your version
of Python and your machine to successfully build LAMMPS. See the
lib/python/README file for more info.
</P>
<P>If you want to write Python code with callbacks to LAMMPS, then you
must also follow the steps overviewed in the preceeding section (11.1)
for running LAMMPS from Python. I.e. you must build LAMMPS as a
shared library and insure that Python can find the python/lammps.py
file and the shared library.
</P>
<HR>
<A NAME = "py_1"></A><H4>11.1 Building LAMMPS as a shared library
<A NAME = "py_3"></A><H4>11.3 Building LAMMPS as a shared library
</H4>
<P>Instructions on how to build LAMMPS as a shared library are given in
<A HREF = "Section_start.html#start_5">Section_start 5</A>. A shared library is one
that is dynamically loadable, which is what Python requires. On Linux
this is a library file that ends in ".so", not ".a".
that is dynamically loadable, which is what Python requires to wrap
LAMMPS. On Linux this is a library file that ends in ".so", not ".a".
</P>
<P>From the src directory, type
<P>>From the src directory, type
</P>
<PRE>make foo mode=shlib
</PRE>
@ -102,7 +200,7 @@ system.
</P>
<HR>
<A NAME = "py_2"></A><H4>11.2 Installing the Python wrapper into Python
<A NAME = "py_4"></A><H4>11.4 Installing the Python wrapper into Python
</H4>
<P>For Python to invoke LAMMPS, there are 2 files it needs to know about:
</P>
@ -170,7 +268,7 @@ environment variable as described above.
</P>
<HR>
<A NAME = "py_3"></A><H4>11.3 Extending Python with MPI to run in parallel
<A NAME = "py_5"></A><H4>11.5 Extending Python with MPI to run in parallel
</H4>
<P>If you wish to run LAMMPS in parallel from Python, you need to extend
your Python with an interface to MPI. This also allows you to
@ -197,11 +295,12 @@ believe) creates a new alternate executable (in place of "python"
itself) as a result.
</P>
<P>In principle any of these Python/MPI packages should work to invoke
LAMMPS in parallel and MPI calls themselves from a Python script which
is itself running in parallel. However, when I downloaded and looked
at a few of them, their documentation was incomplete and I had trouble
with their installation. It's not clear if some of the packages are
still being actively developed and supported.
LAMMPS in parallel and to make MPI calls themselves from a Python
script which is itself running in parallel. However, when I
downloaded and looked at a few of them, their documentation was
incomplete and I had trouble with their installation. It's not clear
if some of the packages are still being actively developed and
supported.
</P>
<P>The one I recommend, since I have successfully used it with LAMMPS, is
Pypar. Pypar requires the ubiquitous <A HREF = "http://numpy.scipy.org">Numpy
@ -261,7 +360,7 @@ the right one.
</P>
<HR>
<A NAME = "py_4"></A><H4>11.4 Testing the Python-LAMMPS interface
<A NAME = "py_6"></A><H4>11.6 Testing the Python-LAMMPS interface
</H4>
<P>To test if LAMMPS is callable from Python, launch Python interactively
and type:
@ -375,22 +474,24 @@ Python on a single processor, not in parallel.
<HR>
<A NAME = "py_5"></A><H4>11.5 Using LAMMPS from Python
<A NAME = "py_7"></A><H4>11.7 Using LAMMPS from Python
</H4>
<P>The Python interface to LAMMPS consists of a Python "lammps" module,
the source code for which is in python/lammps.py, which creates a
"lammps" object, with a set of methods that can be invoked on that
object. The sample Python code below assumes you have first imported
the "lammps" module in your Python script, as follows:
<P>As described above, the Python interface to LAMMPS consists of a
Python "lammps" module, the source code for which is in
python/lammps.py, which creates a "lammps" object, with a set of
methods that can be invoked on that object. The sample Python code
below assumes you have first imported the "lammps" module in your
Python script, as follows:
</P>
<PRE>from lammps import lammps
</PRE>
<P>These are the methods defined by the lammps module. If you look
at the file src/library.cpp you will see that they correspond
one-to-one with calls you can make to the LAMMPS library from a C++ or
C or Fortran program.
<P>These are the methods defined by the lammps module. If you look at
the files src/library.cpp and src/library.h you will see that they
correspond one-to-one with calls you can make to the LAMMPS library
from a C++ or C or Fortran program.
</P>
<PRE>lmp = lammps() # create a LAMMPS object using the default liblammps.so library
lmp = lammps(ptr=lmpptr) # ditto, but use lmpptr as previously created LAMMPS object
lmp = lammps("g++") # create a LAMMPS object using the liblammps_g++.so library
lmp = lammps("",list) # ditto, with command-line args, e.g. list = ["-echo","screen"]
lmp = lammps("g++",list)
@ -449,6 +550,33 @@ processors. If someone figures out how to do this with one or more of
the Python wrappers for MPI, like Pypar, please let us know and we
will amend these doc pages.
</P>
<P>The lines
</P>
<PRE>from lammps import lammps
lmp = lammps()
</PRE>
<P>create an instance of LAMMPS, wrapped in a Python class by the lammps
Python module, and return an instance of the Python class as lmp. It
is used to make all subequent calls to the LAMMPS library.
</P>
<P>Additional arguments can be used to tell Python the name of the shared
library to load or to pass arguments to the LAMMPS instance, the same
as if LAMMPS were launched from a command-line prompt.
</P>
<P>If the ptr argument is set like this:
</P>
<PRE>lmp = lammps(ptr=lmpptr)
</PRE>
<P>then lmpptr must be an argument passed to Python via the LAMMPS
<A HREF = "python.html">python</A> command, when it is used to define a Python
function that is invoked by the LAMMPS input script. This mode of
using Python with LAMMPS is described above in 11.2. The variable
lmpptr refers to the instance of LAMMPS that called the embedded
Python interpreter. Using it as an argument to lammps() allows the
returned Python class instance "lmp" to make calls to that instance of
LAMMPS. See the <A HREF = "python.html">python</A> command doc page for examples
using this syntax.
</P>
<P>Note that you can create multiple LAMMPS objects in your Python
script, and coordinate and run multiple simulations, e.g.
</P>
@ -578,7 +706,7 @@ Python script. Isn't ctypes amazing?
<HR>
<A NAME = "py_6"></A><H4>11.6 Example Python scripts that use LAMMPS
<A NAME = "py_8"></A><H4>11.8 Example Python scripts that use LAMMPS
</H4>
<P>These are the Python scripts included as demos in the python/examples
directory of the LAMMPS distribution, to illustrate the kinds of

268
doc/Section_python.txt
View File

@ -8,61 +8,97 @@
11. Python interface to LAMMPS :h3
This section describes how to build and use LAMMPS via a Python
interface.
LAMMPS can work together with Python in two ways. First, Python can
wrap LAMMPS through the "LAMMPS library
interface"_Section_howto.html#howto_19, so that a Python script can
create one or more instances of LAMMPS and launch one or more
simulations. In Python lingo, this is "extending" Python with LAMMPS.
11.1 "Building LAMMPS as a shared library"_#py_1
11.2 "Installing the Python wrapper into Python"_#py_2
11.3 "Extending Python with MPI to run in parallel"_#py_3
11.4 "Testing the Python-LAMMPS interface"_#py_4
11.5 "Using LAMMPS from Python"_#py_5
11.6 "Example Python scripts that use LAMMPS"_#py_6 :ul
Second, LAMMPS can use the Python interpreter, so that a LAMMPS input
script can invoke Python code, and pass information back-and-forth
between the input script and Python functions you write. The Python
code can also callback to LAMMPS to query or change its attributes.
In Python lingo, this is "embedding" Python in LAMMPS.
The LAMMPS distribution includes the file python/lammps.py which wraps
the library interface to LAMMPS. This file makes it is possible to
run LAMMPS, invoke LAMMPS commands or give it an input script, extract
LAMMPS results, an modify internal LAMMPS variables, either from a
Python script or interactively from a Python prompt. You can do the
former in serial or parallel. Running Python interactively in
parallel does not generally work, unless you have a package installed
that extends your Python to enable multiple instances of Python to
read what you type.
This section describes how to do both.
"Python"_http://www.python.org is a powerful scripting and programming
language which can be used to wrap software like LAMMPS and other
packages. It can be used to glue multiple pieces of software
together, e.g. to run a coupled or multiscale model. See "Section
section"_Section_howto.html#howto_10 of the manual and the couple
directory of the distribution for more ideas about coupling LAMMPS to
other codes. See "Section_start 4"_Section_start.html#start_5 about
how to build LAMMPS as a library, and "Section_howto
19"_Section_howto.html#howto_19 for a description of the library
interface provided in src/library.cpp and src/library.h and how to
extend it for your needs. As described below, that interface is what
is exposed to Python. It is designed to be easy to add functions to.
This can easily extend the Python inteface as well. See details
below.
11.1 "Overview of running LAMMPS from Python"_#py_1
11.2 "Overview of using Python from a LAMMPS script"_#py_2
11.3 "Building LAMMPS as a shared library"_#py_3
11.4 "Installing the Python wrapper into Python"_#py_4
11.5 "Extending Python with MPI to run in parallel"_#py_5
11.6 "Testing the Python-LAMMPS interface"_#py_6
11.7 "Using LAMMPS from Python"_#py_7
11.8 "Example Python scripts that use LAMMPS"_#py_8 :ul
By using the Python interface, LAMMPS can also be coupled with a GUI
or other visualization tools that display graphs or animations in real
time as LAMMPS runs. Examples of such scripts are inlcluded in the
python directory.
If you are not familiar with it, "Python"_http://www.python.org is a
powerful scripting and programming language which can essentially do
anything that faster, lower-level languages like C or C++ can do, but
typically with much fewer lines of code. When used in embedded mode,
Python can perform operations that the simplistic LAMMPS input script
syntax cannot. Python can be also be used as a "glue" language to
drive a program through its library interface, or to hook multiple
pieces of software together, such as a simulation package plus a
visualization package, or to run a coupled multiscale or multiphysics
model.
Two advantages of using Python are how concise the language is, and
that it can be run interactively, enabling rapid development and
debugging of programs. If you use it to mostly invoke costly
operations within LAMMPS, such as running a simulation for a
See "Section_howto 10"_Section_howto.html#howto_10 of the manual and
the couple directory of the distribution for more ideas about coupling
LAMMPS to other codes. See "Section_howto
19"_Section_howto.html#howto_19 for a description of the LAMMPS
library interface provided in src/library.cpp and src/library.h, and
how to extend it for your needs. As described below, that interface
is what is exposed to Python either when calling LAMMPS from Python or
when calling Python from a LAMMPS input script and then calling back
to LAMMPS from Python code. The library interface is designed to be
easy to add functions to. Thus the Python interface to LAMMPS is also
easy to extend as well.
If you create interesting Python scripts that run LAMMPS or
interesting Python functions that can be called from a LAMMPS input
script, that you think would be useful to other users, please "email
them to the developers"_http://lammps.sandia.gov/authors.html. We can
include them in the LAMMPS distribution.
:line
:line
11.1 Overview of running LAMMPS from Python :link(py_1),h4
The LAMMPS distribution includes a python directory with all you need
to run LAMMPS from Python. The python/lammps.py file wraps the LAMMPS
library interface, with one wrapper function per LAMMPS library
function. This file makes it is possible to do the following either
from a Python script, or interactively from a Python prompt: create
one or more instances of LAMMPS, invoke LAMMPS commands or give it an
input script, run LAMMPS incrementally, extract LAMMPS results, an
modify internal LAMMPS variables. From a Python script you can do
this in serial or parallel. Running Python interactively in parallel
does not generally work, unless you have a version of Python that
extends standard Python to enable multiple instances of Python to read
what you type.
To do all of this, you must first build LAMMPS as a shared library,
then insure that your Python can find the python/lammps.py file and
the shared library. These steps are explained in subsequent sections
11.3 and 11.4. Sections 11.5 and 11.6 discuss using MPI from a
parallel Python program and how to test that you are ready to use
LAMMPS from Python. Section 11.7 lists all the functions in the
current LAMMPS library interface and how to call them from Python.
Section 11.8 gives some examples of coupling LAMMPS to other tools via
Python. For example, LAMMPS can easily be coupled to a GUI or other
visualization tools that display graphs or animations in real time as
LAMMPS runs. Examples of such scripts are inlcluded in the python
directory.
Two advantages of using Python to run LAMMPS are how concise the
language is, and that it can be run interactively, enabling rapid
development and debugging of programs. If you use it to mostly invoke
costly operations within LAMMPS, such as running a simulation for a
reasonable number of timesteps, then the overhead cost of invoking
LAMMPS thru Python will be negligible.
Before using LAMMPS from a Python script, you need to do two things.
You need to build LAMMPS as a dynamic shared library, so it can be
loaded by Python. And you need to tell Python how to find the library
and the Python wrapper file python/lammps.py. Both these steps are
discussed below. If you wish to run LAMMPS in parallel from Python,
you also need to extend your Python with MPI. This is also discussed
below.
The Python wrapper for LAMMPS uses the amazing and magical (to me)
"ctypes" package in Python, which auto-generates the interface code
needed between Python and a set of C interface routines for a library.
@ -71,16 +107,78 @@ check which version of Python you have installed, by simply typing
"python" at a shell prompt.
:line
11.2 Overview of using Python from a LAMMPS script :link(py_2),h4
LAMMPS has a "python"_python.html command which can be used in an
input script to define and execute a Python function that you write
the code for. The Python function can also be assigned to a LAMMPS
python-style variable via the "variable"_variable.html command. Each
time the variable is evaluated, either in the LAMMPS input script
itself, or by another LAMMPS command that uses the variable, this will
trigger the Python function to be invoked.
The Python code for the function can be included directly in the input
script or in an auxiliary file. The function can have arguments which
are mapped to LAMMPS variables (also defined in the input script) and
it can return a value to a LAMMPS variable. This is thus a mechanism
for your input script to pass information to a piece of Python code,
ask Python to execute the code, and return information to your input
script.
Note that a Python function can be arbitrarily complex. It can import
other Python modules, instantiate Python classes, call other Python
functions, etc. The Python code that you provide can contain more
code than the single function. It can contain other functions or
Python classes, as well as global variables or other mechanisms for
storing state between calls from LAMMPS to the function.
The Python function you provide can consist of "pure" Python code that
only performs operations provided by standard Python. However, the
Python function can also "call back" to LAMMPS through its
Python-wrapped library interface, in the manner described in the
previous section 11.1. This means it can issue LAMMPS input script
commands or query and set internal LAMMPS state. As an example, this
can be useful in an input script to create a more complex loop with
branching logic, than can be created using the simple looping and
brancing logic enabled by the "next"_next_html and "if"_if.html
commands.
See the "python"_python.html doc page and the "variable"_variable.html
doc page for its python-style variables for more info, including
examples of Python code you can write for both pure Python operations
and callbacks to LAMMPS.
To run pure Python code from LAMMPS, you only need to build LAMMPS
with the PYTHON package installed:
make yes-python
make machine
Note that this will link LAMMPS with the Python library on your
system, which typically requires several auxiliary system libraries to
also be linked. The list of these libraries and the paths to find
them are specified in the lib/python/Makefile.lammps file. You need
to insure that file contains the correct information for your version
of Python and your machine to successfully build LAMMPS. See the
lib/python/README file for more info.
If you want to write Python code with callbacks to LAMMPS, then you
must also follow the steps overviewed in the preceeding section (11.1)
for running LAMMPS from Python. I.e. you must build LAMMPS as a
shared library and insure that Python can find the python/lammps.py
file and the shared library.
:line
11.1 Building LAMMPS as a shared library :link(py_1),h4
11.3 Building LAMMPS as a shared library :link(py_3),h4
Instructions on how to build LAMMPS as a shared library are given in
"Section_start 5"_Section_start.html#start_5. A shared library is one
that is dynamically loadable, which is what Python requires. On Linux
this is a library file that ends in ".so", not ".a".
that is dynamically loadable, which is what Python requires to wrap
LAMMPS. On Linux this is a library file that ends in ".so", not ".a".
From the src directory, type
>From the src directory, type
make foo mode=shlib :pre
@ -98,7 +196,7 @@ system.
:line
11.2 Installing the Python wrapper into Python :link(py_2),h4
11.4 Installing the Python wrapper into Python :link(py_4),h4
For Python to invoke LAMMPS, there are 2 files it needs to know about:
@ -166,7 +264,7 @@ environment variable as described above.
:line
11.3 Extending Python with MPI to run in parallel :link(py_3),h4
11.5 Extending Python with MPI to run in parallel :link(py_5),h4
If you wish to run LAMMPS in parallel from Python, you need to extend
your Python with an interface to MPI. This also allows you to
@ -193,11 +291,12 @@ believe) creates a new alternate executable (in place of "python"
itself) as a result.
In principle any of these Python/MPI packages should work to invoke
LAMMPS in parallel and MPI calls themselves from a Python script which
is itself running in parallel. However, when I downloaded and looked
at a few of them, their documentation was incomplete and I had trouble
with their installation. It's not clear if some of the packages are
still being actively developed and supported.
LAMMPS in parallel and to make MPI calls themselves from a Python
script which is itself running in parallel. However, when I
downloaded and looked at a few of them, their documentation was
incomplete and I had trouble with their installation. It's not clear
if some of the packages are still being actively developed and
supported.
The one I recommend, since I have successfully used it with LAMMPS, is
Pypar. Pypar requires the ubiquitous "Numpy
@ -257,7 +356,7 @@ the right one.
:line
11.4 Testing the Python-LAMMPS interface :link(py_4),h4
11.6 Testing the Python-LAMMPS interface :link(py_6),h4
To test if LAMMPS is callable from Python, launch Python interactively
and type:
@ -370,22 +469,24 @@ Python on a single processor, not in parallel.
:line
:line
11.5 Using LAMMPS from Python :link(py_5),h4
11.7 Using LAMMPS from Python :link(py_7),h4
The Python interface to LAMMPS consists of a Python "lammps" module,
the source code for which is in python/lammps.py, which creates a
"lammps" object, with a set of methods that can be invoked on that
object. The sample Python code below assumes you have first imported
the "lammps" module in your Python script, as follows:
As described above, the Python interface to LAMMPS consists of a
Python "lammps" module, the source code for which is in
python/lammps.py, which creates a "lammps" object, with a set of
methods that can be invoked on that object. The sample Python code
below assumes you have first imported the "lammps" module in your
Python script, as follows:
from lammps import lammps :pre
These are the methods defined by the lammps module. If you look
at the file src/library.cpp you will see that they correspond
one-to-one with calls you can make to the LAMMPS library from a C++ or
C or Fortran program.
These are the methods defined by the lammps module. If you look at
the files src/library.cpp and src/library.h you will see that they
correspond one-to-one with calls you can make to the LAMMPS library
from a C++ or C or Fortran program.
lmp = lammps() # create a LAMMPS object using the default liblammps.so library
lmp = lammps(ptr=lmpptr) # ditto, but use lmpptr as previously created LAMMPS object
lmp = lammps("g++") # create a LAMMPS object using the liblammps_g++.so library
lmp = lammps("",list) # ditto, with command-line args, e.g. list = \["-echo","screen"\]
lmp = lammps("g++",list) :pre
@ -444,6 +545,33 @@ processors. If someone figures out how to do this with one or more of
the Python wrappers for MPI, like Pypar, please let us know and we
will amend these doc pages.
The lines
from lammps import lammps
lmp = lammps() :pre
create an instance of LAMMPS, wrapped in a Python class by the lammps
Python module, and return an instance of the Python class as lmp. It
is used to make all subequent calls to the LAMMPS library.
Additional arguments can be used to tell Python the name of the shared
library to load or to pass arguments to the LAMMPS instance, the same
as if LAMMPS were launched from a command-line prompt.
If the ptr argument is set like this:
lmp = lammps(ptr=lmpptr) :pre
then lmpptr must be an argument passed to Python via the LAMMPS
"python"_python.html command, when it is used to define a Python
function that is invoked by the LAMMPS input script. This mode of
using Python with LAMMPS is described above in 11.2. The variable
lmpptr refers to the instance of LAMMPS that called the embedded
Python interpreter. Using it as an argument to lammps() allows the
returned Python class instance "lmp" to make calls to that instance of
LAMMPS. See the "python"_python.html command doc page for examples
using this syntax.
Note that you can create multiple LAMMPS objects in your Python
script, and coordinate and run multiple simulations, e.g.
@ -572,7 +700,7 @@ Python script. Isn't ctypes amazing? :l,ule
:line
:line
11.6 Example Python scripts that use LAMMPS :link(py_6),h4
11.8 Example Python scripts that use LAMMPS :link(py_8),h4
These are the Python scripts included as demos in the python/examples
directory of the LAMMPS distribution, to illustrate the kinds of

32
doc/Section_start.html
View File

@ -171,7 +171,7 @@ all good starting points if you find you need to change them for your
machine. Put any file you edit into the src/MAKE/MINE directory and
it will be never be touched by any LAMMPS updates.
</P>
<P>From within the src directory, type "make" or "gmake". You should see
<P>>From within the src directory, type "make" or "gmake". You should see
a list of available choices from src/MAKE and all of its
sub-directories. If one of those has the options you want or is the
machine you want, you can type a command like:
@ -772,20 +772,30 @@ options.
<A NAME = "start_3_3"></A><B><I>Packages that require extra libraries:</I></B>
<P>A few of the standard and user packages require additional auxiliary
libraries. They must be compiled first, before LAMMPS is built. If
you get a LAMMPS build error about a missing library, this is likely
the reason. See the <A HREF = "Section_packages.html">Section_packages</A> doc page
for a list of packages that have auxiliary libraries.
libraries. Most of them are provided with LAMMPS, in which case they
must be compiled first, before LAMMPS is built if you wish to include
that package. If you get a LAMMPS build error about a missing
library, this is likely the reason. See the
<A HREF = "Section_packages.html">Section_packages</A> doc page for a list of
packages that have these kinds of auxiliary libraries.
</P>
<P>The lib directory in the distribution has sub-directories with package
names that correspond to the needed auxiliary libs, e.g. lib/reax.
names that correspond to the needed auxiliary libs, e.g. lib/reax.
Each sub-directory has a README file that gives more details. Code
for most of the auxiliary libraries is included in that directory.
Examples are the USER-ATC and MEAM packages. A few of the
sub-directories do not include code, but do include instructions and
sometimes scripts that automate the process of downloading the
auxiliary library and installing it so LAMMPS can link to it.
Examples are the KIM and VORONOI and USER-MOLFILE packages.
Examples are the USER-ATC and MEAM packages.
</P>
<P>A few of the lib sub-directories do not include code, but do include
instructions and sometimes scripts that automate the process of
downloading the auxiliary library and installing it so LAMMPS can link
to it. Examples are the KIM and VORONOI and USER-MOLFILE packages.
</P>
<P>The lib/python directory (for the PYTHON package) contains only a
choice of Makefile.lammps.* files. This is because no auxiliary code
or libraries are needed, only the Python library and other system libs
that already available on your system. However, the Makefile.lammps
file is needed to tell the LAMMPS build which libs to use and where to
find them.
</P>
<P>For libraries with provided code, the sub-directory README file
(e.g. lib/reax/README) has instructions on how to build that library.

32
doc/Section_start.txt
View File

@ -165,7 +165,7 @@ all good starting points if you find you need to change them for your
machine. Put any file you edit into the src/MAKE/MINE directory and
it will be never be touched by any LAMMPS updates.
From within the src directory, type "make" or "gmake". You should see
>From within the src directory, type "make" or "gmake". You should see
a list of available choices from src/MAKE and all of its
sub-directories. If one of those has the options you want or is the
machine you want, you can type a command like:
@ -766,20 +766,30 @@ options.
[{Packages that require extra libraries:}] :link(start_3_3)
A few of the standard and user packages require additional auxiliary
libraries. They must be compiled first, before LAMMPS is built. If
you get a LAMMPS build error about a missing library, this is likely
the reason. See the "Section_packages"_Section_packages.html doc page
for a list of packages that have auxiliary libraries.
libraries. Most of them are provided with LAMMPS, in which case they
must be compiled first, before LAMMPS is built if you wish to include
that package. If you get a LAMMPS build error about a missing
library, this is likely the reason. See the
"Section_packages"_Section_packages.html doc page for a list of
packages that have these kinds of auxiliary libraries.
The lib directory in the distribution has sub-directories with package
names that correspond to the needed auxiliary libs, e.g. lib/reax.
names that correspond to the needed auxiliary libs, e.g. lib/reax.
Each sub-directory has a README file that gives more details. Code
for most of the auxiliary libraries is included in that directory.
Examples are the USER-ATC and MEAM packages. A few of the
sub-directories do not include code, but do include instructions and
sometimes scripts that automate the process of downloading the
auxiliary library and installing it so LAMMPS can link to it.
Examples are the KIM and VORONOI and USER-MOLFILE packages.
Examples are the USER-ATC and MEAM packages.
A few of the lib sub-directories do not include code, but do include
instructions and sometimes scripts that automate the process of
downloading the auxiliary library and installing it so LAMMPS can link
to it. Examples are the KIM and VORONOI and USER-MOLFILE packages.
The lib/python directory (for the PYTHON package) contains only a
choice of Makefile.lammps.* files. This is because no auxiliary code
or libraries are needed, only the Python library and other system libs
that already available on your system. However, the Makefile.lammps
file is needed to tell the LAMMPS build which libs to use and where to
find them.
For libraries with provided code, the sub-directory README file
(e.g. lib/reax/README) has instructions on how to build that library.

20
doc/print.html
View File

@ -13,8 +13,8 @@
</H3>
<P><B>Syntax:</B>
</P>
<P>print string keyword value:pre
</P>
<PRE>print string keyword value
</PRE>
<UL><LI>string = text string to print, which may contain variables
<LI>zero or more keyword/value pairs may be appended
@ -32,14 +32,20 @@
<PRE>print "Done with equilibration" file info.dat
print Vol=$v append info.dat screen no
print "The system volume is now $v"
print 'The system volume is now $v'
print 'The system volume is now $v'
print """
System volume = $v
System temperature = $t
"""
</PRE>
<P><B>Description:</B>
</P>
<P>Print a text string to the screen and logfile. One line of output is
generated. The text string must be a single argument, so it should be
enclosed in double quotes if it is more than one word. If it contains
variables, they will be evaluated and their current values printed.
<P>Print a text string to the screen and logfile. The text string must
be a single argument, so if it is one line but more than one word, it
should be enclosed in single or double quotes. To generate multiple
lines of output, the string can be enclosed in triple quotes, as in
the last example above. If the text string contains variables, they
will be evaluated and their current values printed.
</P>
<P>If the <I>file</I> or <I>append</I> keyword is used, a filename is specified to
which the output will be written. If <I>file</I> is used, then the

19
doc/print.txt
View File

@ -10,7 +10,7 @@ print command :h3
[Syntax:]
print string keyword value:pre
print string keyword value :pre
string = text string to print, which may contain variables :ulb,l
zero or more keyword/value pairs may be appended :l
@ -25,14 +25,20 @@ keyword = {file} or {append} or {screen} :l
print "Done with equilibration" file info.dat
print Vol=$v append info.dat screen no
print "The system volume is now $v"
print 'The system volume is now $v' :pre
print 'The system volume is now $v'
print """
System volume = $v
System temperature = $t
""" :pre
[Description:]
Print a text string to the screen and logfile. One line of output is
generated. The text string must be a single argument, so it should be
enclosed in double quotes if it is more than one word. If it contains
variables, they will be evaluated and their current values printed.
Print a text string to the screen and logfile. The text string must
be a single argument, so if it is one line but more than one word, it
should be enclosed in single or double quotes. To generate multiple
lines of output, the string can be enclosed in triple quotes, as in
the last example above. If the text string contains variables, they
will be evaluated and their current values printed.
If the {file} or {append} keyword is used, a filename is specified to
which the output will be written. If {file} is used, then the
@ -69,4 +75,3 @@ thermodynamic properties, global values calculated by a
[Default:]
The option defaults are no file output and screen = yes.

485
doc/python.html Normal file
View File

@ -0,0 +1,485 @@
<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>python command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>python func keyword args ...
</PRE>
<UL><LI>func = name of Python function
<LI>one or more keyword/args pairs must be appended
<PRE>keyword = <I>invoke</I> or <I>input</I> or <I>return</I> or <I>format</I> or <I>file</I> or <I>here</I> or <I>exists</I>
<I>invoke</I> arg = none = invoke the previously defined Python function
<I>input</I> args = N i1 i2 ... iN
N = # of inputs to function
i1,...,iN = value, SELF, or LAMMPS variable name
value = integer number, floating point number, or string
SELF = reference to LAMMPS itself which can be accessed by Python function
variable = v_name, where name = name of LAMMPS variable, e.g. v_abc
<I>return</I> arg = varReturn
varReturn = v_name = LAMMPS variable name which return value of function will be assigned to
<I>format</I> arg = fstring with M characters
M = N if no return value, where N = # of inputs
M = N+1 if there is a return value
fstring = each character (i,f,s,p) corresponds in order to an input or return value
'i' = integer, 'f' = floating point, 's' = string, 'p' = SELF
<I>file</I> arg = filename
filename = file of Python code, which defines func
<I>here</I> arg = inline
inline = one or more lines of Python code which defines func
must be a single argument, typically enclosed between triple quotes
<I>exists</I> arg = none = Python code has been loaded by previous python command
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>python pForce input 2 v_x 20.0 return v_f format fff file force.py
python pForce invoke
</PRE>
<PRE>python factorial input 1 myN return v_fac format ii here """
def factorial(n):
if n == 1: return n
return n * factorial(n-1)
"""
</PRE>
<PRE>python loop input 1 SELF return v_value format -f here """
def loop(lmpptr,N,cut0):
from lammps import lammps
lmp = lammps(ptr=lmpptr)
</PRE>
<PRE> # loop N times, increasing cutoff each time
</PRE>
<PRE> for i in range(N):
cut = cut0 + i*0.1
lmp.set_variable("cut",cut) # set a variable in LAMMPS
lmp.command("pair_style lj/cut $<I>cut</I>") # LAMMPS commands
lmp.command("pair_coeff * * 1.0 1.0")
lmp.command("run 100")
"""
</PRE>
<P><B>Description:</B>
</P>
<P>Define a Python function or execute a previously defined function.
Arguments, including LAMMPS variables, can be passed to the function
from the LAMMPS input script and a value returned by the Python
function to a LAMMPS variable. The Python code for the function can
be included directly in the input script or in a separate Python file.
The function can be standard Python code or it can make "callbacks" to
LAMMPS through its library interface to query or set internal values
within LAMMPS. This is a powerful mechanism for performing complex
operations in a LAMMPS input script that are not possible with the
simple input script and variable syntax which LAMMPS defines. Thus
your input script can operate more like a true programming language.
</P>
<P>Use of this command requires building LAMMPS with the PYTHON package
which links to the Python library so that the Python interpreter is
embedded in LAMMPS. More details about this process are given below.
</P>
<P>There are two ways to invoke a Python function once it has been
defined. One is using the <I>invoke</I> keyword. The other is to assign
the function to a <A HREF = "variable.html">python-style variable</A> defined in
your input script. Whenever the variable is evaluated, it will
execute the Python function to assign a value to the variable. Note
that variables can be evaluated in many different ways within LAMMPS.
They can be substituted for directly in an input script. Or they can
be passed to various commands as arguments, so that the variable is
evaluated during a simulation run.
</P>
<P>A broader overview of how Python can be used with LAMMPS is
given in <A HREF = "Section_python.html">Section python</A>. There is an
examples/python directory which illustrates use of the python
command.
</P>
<HR>
<P>The <I>func</I> setting specifies the name of the Python function. The
code for the function is defined using the <I>file</I> or <I>here</I> keywords
as explained below.
</P>
<P>If the <I>invoke</I> keyword is used, no other keywords can be used, and a
previous python command must have defined the Python function
referenced by this command. This invokes the Python function with the
previously defined arguments and return value processed as explained
below. You can invoke the function as many times as you wish in your
input script.
</P>
<P>The <I>input</I> keyword defines how many arguments <I>N</I> the Python function
expects. If it takes no arguments, then the <I>input</I> keyword should
not be used. Each argument can be specified directly as a value,
e.g. 6 or 3.14159 or abc (a string of characters). The type of each
argument is specified by the <I>format</I> keyword as explained below, so
that Python will know how to interpret the value. If the word SELF is
used for an argument it has a special meaning. A pointer is passed to
the Python function which it converts into a reference to LAMMPS
itself. This enables the function to call back to LAMMPS through its
library interface as explained below. This allows the Python function
to query or set values internal to LAMMPS which can affect the
subsequent execution of the input script. A LAMMPS variable can also
be used as an argument, specified as v_name, where "name" is the name
of the variable. Any style of LAMMPS variable can be used, as defined
by the <A HREF = "variable.html">variable</A> command. Each time the Python
function is invoked, the LAMMPS variable is evaluated and its value is
passed to the Python function.
</P>
<P>The <I>return</I> keyword is only needed if the Python function returns a
value. The specified <I>varReturn</I> must be of the form v_name, where
"name" is the name of a python-style LAMMPS variable, defined by the
<A HREF = "variable.html">variable</A> command. The Python function can return a
numeric or string value, as specified by the <I>format</I> keyword.
</P>
<P>As explained on the <A HREF = "variable.html">variable</A> doc page, the definition
of a python-style variable associates a Python function name with the
variable. This must match the <I>func</I> setting for this command. For
exampe these two commands would be self-consistent:
</P>
<PRE>variable foo python myMultiply
python myMultiply return v_foo format f file funcs.py
</PRE>
<P>The two commands can appear in either order in the input script so
long as both are specified before the Python function is invoked for
the first time.
</P>
<P>The <I>format</I> keyword must be used if the <I>input</I> or <I>return</I> keyword
is used. It defines an <I>fstring</I> with M characters, where M = sum of
number of inputs and outputs. The order of characters corresponds to
the N inputs, followed by the return value (if it exists). Each
character must be one of the following: "i" for integer, "f" for
floating point, "s" for string, or "p" for SELF. Each character
defines the type of the corresponding input or output value of the
Python function and affects the type conversion that is performed
internally as data is passed back and forth between LAMMPS and Python.
Note that it is permissible to use a <A HREF = "variable.html">python-style
variable</A> in a LAMMPS command that allows for an
equal-style variable as an argument, but only if the output of the
Python function is flagged as a numeric value ("i" or "f") via the
<I>format</I> keyword.
</P>
<P>Either the <I>file</I>, <I>here</I>, or <I>exists</I> keyword must be used, but only
one of them. These keywords specify what Python code to load into the
Python interpreter. The <I>file</I> keyword gives the name of a file,
which should end with a ".py" suffix, which contains Python code. The
code will be immediately loaded into and run in the "main" module of
the Python interpreter. Note that Python code which contains a
function definition does not "execute" the function when it is run; it
simply defines the function so that it can be invoked later.
</P>
<P>The <I>here</I> keyword does the same thing, except that the Python code
follows as a single argument to the <I>here</I> keyword. This can be done
using triple quotes as delimiters, as in the examples above. This
allows Python code to be listed verbatim in your input script, with
proper indentation, blank lines, and comments, as desired. See
<A HREF = "Section_commands.html#cmd_2">Section 3.2</A>, for an explanation of how
triple quotes can be used as part of input script syntax.
</P>
<P>The <I>exists</I> keyword takes no argument. It means that Python code
containing the required Python function defined by the <I>func</I> setting,
is assumed to have been previously loaded by another python command.
</P>
<P>Note that the Python code that is loaded and run must contain a
function with the specified <I>func</I> name. To operate properly when
later invoked, the the function code must match the <I>input</I> and
<I>return</I> and <I>format</I> keywords specified by the python command.
Otherwise Python will generate an error.
</P>
<HR>
<P>This section describes how Python code can be written to work with
LAMMPS.
</P>
<P>Whether you load Python code from a file or directly from your input
script, via the <I>file</I> and <I>here</I> keywords, the code can be identical.
It must be indented properly as Python requires. It can contain
comments or blank lines. If the code is in your input script, it
cannot however contain triple-quoted Python strings, since that will
conflict with the triple-quote parsing that the LAMMPS input script
performs.
</P>
<P>All the Python code you specify via one or more python commands is
loaded into the Python "main" module, i.e. __main__. The code can
define global variables or statements that are outside of function
definitions. It can contain multiple functions, only one of which
matches the <I>func</I> setting in the python command. This means you can
use the <I>file</I> keyword once to load several functions, and the
<I>exists</I> keyword thereafter in subsequent python commands to access
the other functions previously loaded.
</P>
<P>A Python function you define (or more generally, the code you load)
can import other Python modules or classes, it can make calls to other
system functions or functions you define, and it can access or modify
global variables (in the "main" module) which will persist between
successive function calls. The latter can be useful, for example, to
prevent a function from being invoke multiple times per timestep by
different commands in a LAMMPS input script that access the returned
python-style variable associated with the function. For example,
consider this function loaded with two global variables defined
outside the function:
</P>
<PRE>nsteplast = -1
nvaluelast = 0
</PRE>
<PRE>def expensive(nstep):
global nsteplast,nvaluelast
if nstep == nsteplast: return nvaluelast
nsteplast = nstep
# perform complicated calculation
nvalue = ...
nvaluelast = nvalue
return nvalue
</PRE>
<P>Nsteplast stores the previous timestep the function was invoked
(passed as an argument to the function). Nvaluelast stores the return
value computed on the last function invocation. If the function is
invoked again on the same timestep, the previous value is simply
returned, without re-computing it. The "global" statement inside the
Python function allows it to overwrite the global variables.
</P>
<P>Note that if you load Python code multiple times (via multiple python
commands), you can overwrite previously loaded variables and functions
if you are not careful. E.g. if the code above were loaded twice, the
global variables would be re-initialized, which might not be what you
want. Likewise, if a function with the same name exists in two chunks
of Python code you load, the function loaded second will override the
function loaded first.
</P>
<P>It's important to realize that if you are running LAMMPS in parallel,
each MPI task will load the Python interpreter and execute a local
copy of the Python function(s) you define. There is no connection
between the Python interpreters running on different processors.
This implies three important things.
</P>
<P>First, if you put a print statement in your Python function, you will
see P copies of the output, when running on P processors. If the
prints occur at (nearly) the same time, the P copies of the output may
be mixed together. Welcome to the world of parallel programming and
debugging.
</P>
<P>Second, if your Python code loads modules that are not pre-loaded by
the Python library, then it will load the module from disk. This may
be a bottleneck if 1000s of processors try to load a module at the
same time. On some large supercomputers, loading of modules from disk
by Python may be disabled. In this case you would need to pre-build a
Python library that has the required modules pre-loaded and link
LAMMPS with that library.
</P>
<P>Third, if your Python code calls back to LAMMPS (discussed in the
next section) and causes LAMMPS to perform an MPI operation requires
global communication (e.g. via MPI_Allreduce), such as computing the
global temperature of the system, then you must insure all your Python
functions (running independently on different processors) call back to
LAMMPS. Otherwise the code may hang.
</P>
<HR>
<P>Your Python function can "call back" to LAMMPS through its
library interface, if you use the SELF input to pass Python
a pointer to LAMMPS. The mechanism for doing this in your
Python function is as follows:
</P>
<PRE>def foo(lmpptr,...):
from lammps import lammps
lmp = lammps(ptr=lmpptr)
lmp.command('print "Hello from inside Python"')
...
</PRE>
<P>The function definition must include a variable (lmpptr in this case)
which corresponds to SELF in the python command. The first line of
the function imports the Python module lammps.py in the python dir of
the distribution. The second line creates a Python object "lmp" which
wraps the instance of LAMMPS that called the function. The
"ptr=lmpptr" argument is what makes that happen. The thrid line
invokes the command() function in the LAMMPS library interface. It
takes a single string argument which is a LAMMPS input script command
for LAMMPS to execute, the same as if it appeared in your input
script. In this case, LAMMPS should output
</P>
<PRE>Hello from inside Python
</PRE>
<P>to the screen and log file. Note that since the LAMMPS print command
itself takes a string in quotes as its argument, the Python string
must be delimited with a different style of quotes.
</P>
<P><A HREF = "Section_python.html#py_7">Section 11.7</A> describes the syntax for how
Python wraps the various functions included in the LAMMPS library
interface.
</P>
<P>A more interesting example is in the examples/python/in.python script
which loads and runs the following function from examples/python/funcs.py:
</P>
<PRE>def loop(N,cut0,thresh,lmpptr):
print "LOOP ARGS",N,cut0,thresh,lmpptr
from lammps import lammps
lmp = lammps(ptr=lmpptr)
natoms = lmp.get_natoms()
</PRE>
<PRE> for i in range(N):
cut = cut0 + i*0.1
</PRE>
<PRE> lmp.set_variable("cut",cut) # set a variable in LAMMPS
lmp.command("pair_style lj/cut $<I>cut</I>") # LAMMPS command
#lmp.command("pair_style lj/cut %d" % cut) # LAMMPS command option
</PRE>
<PRE> lmp.command("pair_coeff * * 1.0 1.0") # ditto
lmp.command("run 10") # ditto
pe = lmp.extract_compute("thermo_pe",0,0) # extract total PE from LAMMPS
print "PE",pe/natoms,thresh
if pe/natoms < thresh: return
</PRE>
<P>with these input script commands:
</P>
<PRE>python loop input 4 10 1.0 -4.0 SELF format iffp file funcs.py
python loop invoke
</PRE>
<P>This has the effect of looping over a series of 10 short runs (10
timesteps each) where the pair style cutoff is increased from a value
of 1.0 in distance units, in increments of 0.1. The looping stops
when the per-atom potential energy falls below a threshhold of -4.0 in
energy units. More generally, Python can be used to implement a loop
with complex logic, much more so than can be created using the LAMMPS
<A HREF = "jump.html">jump</A> and <A HREF = "if.html">if</A> commands.
</P>
<P>Several LAMMPS library functions are called from the loop function.
Get_natoms() returns the number of atoms in the simulation, so that it
can be used to normalize the potential energy that is returned by
extract_compute() for the "thermo_pe" compute that is defined by
default for LAMMPS thermodynamic output. Set_variable() sets the
value of a string variable defined in LAMMPS. This library function
is a useful way for a Python function to return multiple values to
LAMMPS, more than the single value that can be passed back via a
return statement. This cutoff value in the "cut" variable is then
substituted (by LAMMPS) in the pair_style command that is executed
next. Alternatively, the "LAMMPS command option" line could be used
in place of the 2 preceeding lines, to have Python insert the value
into the LAMMPS command string.
</P>
<P>IMPORTANT NOTE: When using the callback mechanism just described,
recognize that there are some operations you should not attempt
because LAMMPS cannot execute them correctly. If the Python function
is invoked between runs in the LAMMPS input script, then it should be
OK to invoke any LAMMPS input script command via the library interface
command() or file() functions, so long as the command would work if it
were executed in the LAMMPS input script directly at the same point.
</P>
<P>However, a Python function can also be invoked during a run, whenever
an associated LAMMPS variable it is assigned to is evaluted. If the
variable is an input argument to another LAMMPS command (e.g. <A HREF = "fix_setforce.html">fix
setforce</A>), then the Python function will be invoked
inside the class for that command, in one of its methods that is
invoked in the middle of a timestep. You cannot execute arbitrary
input script commands from the Python function (again, via the
command() or file() functions) at that point in the run and expect it
to work. Other library functions such as those that invoke computes
or other variables may have hidden side effects as well. In these
cases, LAMMPS has no simple way to check that something illogical is
being attempted.
</P>
<HR>
<P>If you run Python code directly on your workstation, either
interactively or by using Python to launch a Python script stored in a
file, and your code has an error, you will typically see informative
error messages. That is not the case when you run Python code from
LAMMPS using an embedded Python interpreter. The code will typically
fail silently. LAMMPS will catch some errors but cannot tell you
where in the Python code the problem occurred. For example, if the
Python code cannot be loaded and run because it has syntax or other
logic errors, you may get an error from Python pointing to the
offending line, or you may get one of these generic errors from
LAMMPS:
</P>
<PRE>Could not process Python file
Could not process Python string
</PRE>
<P>When the Python function is invoked, if it does not return properly,
you will typically get this generic error from LAMMPS:
</P>
<PRE>Python function evaluation failed
</PRE>
<P>Here are three suggestions for debugging your Python code while
running it under LAMMPS.
</P>
<P>First, don't run it under LAMMPS, at least to start with! Debug it
using plain Python. Load and invoke your function, pass it arguments,
check return values, etc.
</P>
<P>Second, add Python print statements to the function to check how far
it gets and intermediate values it calculates. See the discussion
above about printing from Python when running in parallel.
</P>
<P>Third, use Python exception handling. For example, say this statement
in your Python function is failing, because you have not initialized the
variable foo:
</P>
<PRE>foo += 1
</PRE>
<P>If you put one (or more) statements inside a "try" statement,
like this:
</P>
<PRE>import exceptions
print "Inside simple function"
try:
foo += 1 # one or more statements here
except Exception, e:
print "FOO error:",e
</PRE>
<P>then you will get this message printed to the screen:
</P>
<PRE>FOO error: local variable 'foo' referenced before assignment
</PRE>
<P>If there is no error in the try statements, then nothing is printed.
Either way the function continues on (unless you put a return or
sys.exit() in the except clause).
</P>
<HR>
<P><B>Restrictions:</B>
</P>
<P>This command is part of the PYTHON package. It is only enabled if
LAMMPS was built with that package. See the <A HREF = "Section_start.html#start_3">Making
LAMMPS</A> section for more info.
</P>
<P>Building LAMMPS with the PYTHON package will link LAMMPS with the
Python library on your system. Settings to enable this are in the
lib/python/Makefile.lammps file. See the lib/python/README file for
information on those settings.
</P>
<P>If you use Python code which calls back to LAMMPS, via the SELF input
argument explained above, there is an extra step required when
building LAMMPS. LAMMPS must also be built as a shared library and
your Python function must be able to to load the Python module in
python/lammps.py that wraps the LAMMPS library interface. These are
the same steps required to use Python by itself to wrap LAMMPS.
Details on these steps are explained in <A HREF = "Section.python.html">Section
python</A>. Note that it is important that the
stand-alone LAMMPS executable and the LAMMPS shared library be
consistent (built from the same source code files) in order for this
to work. If the two have been built at different times using
different source files, problems may occur.
</P>
<P>As described above, you can use the python command to invoke a Python
function which calls back to LAMMPS through its Python-wrapped library
interface. However you cannot do the opposite. I.e. you cannot call
LAMMPS from Python and invoke the python command to "callback" to
Python and execute a Python function. LAMMPS will generate an error
if you try to do that. Note that we think there actually should be a
way to do that, but haven't yet been able to figure out how to do it
successfully.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "shell.html">shell</A>, <A HREF = "variable.html">variable</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>

477
doc/python.txt Normal file
View File

@ -0,0 +1,477 @@
"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
python command :h3
[Syntax:]
python func keyword args ... :pre
func = name of Python function :ulb,l
one or more keyword/args pairs must be appended :l
keyword = {invoke} or {input} or {return} or {format} or {file} or {here} or {exists}
{invoke} arg = none = invoke the previously defined Python function
{input} args = N i1 i2 ... iN
N = # of inputs to function
i1,...,iN = value, SELF, or LAMMPS variable name
value = integer number, floating point number, or string
SELF = reference to LAMMPS itself which can be accessed by Python function
variable = v_name, where name = name of LAMMPS variable, e.g. v_abc
{return} arg = varReturn
varReturn = v_name = LAMMPS variable name which return value of function will be assigned to
{format} arg = fstring with M characters
M = N if no return value, where N = # of inputs
M = N+1 if there is a return value
fstring = each character (i,f,s,p) corresponds in order to an input or return value
'i' = integer, 'f' = floating point, 's' = string, 'p' = SELF
{file} arg = filename
filename = file of Python code, which defines func
{here} arg = inline
inline = one or more lines of Python code which defines func
must be a single argument, typically enclosed between triple quotes
{exists} arg = none = Python code has been loaded by previous python command :pre
:ule
[Examples:]
python pForce input 2 v_x 20.0 return v_f format fff file force.py
python pForce invoke :pre
python factorial input 1 myN return v_fac format ii here """
def factorial(n):
if n == 1: return n
return n * factorial(n-1)
""" :pre
python loop input 1 SELF return v_value format -f here """
def loop(lmpptr,N,cut0):
from lammps import lammps
lmp = lammps(ptr=lmpptr) :pre
# loop N times, increasing cutoff each time :pre
for i in range(N):
cut = cut0 + i*0.1
lmp.set_variable("cut",cut) # set a variable in LAMMPS
lmp.command("pair_style lj/cut ${cut}") # LAMMPS commands
lmp.command("pair_coeff * * 1.0 1.0")
lmp.command("run 100")
""" :pre
[Description:]
Define a Python function or execute a previously defined function.
Arguments, including LAMMPS variables, can be passed to the function
from the LAMMPS input script and a value returned by the Python
function to a LAMMPS variable. The Python code for the function can
be included directly in the input script or in a separate Python file.
The function can be standard Python code or it can make "callbacks" to
LAMMPS through its library interface to query or set internal values
within LAMMPS. This is a powerful mechanism for performing complex
operations in a LAMMPS input script that are not possible with the
simple input script and variable syntax which LAMMPS defines. Thus
your input script can operate more like a true programming language.
Use of this command requires building LAMMPS with the PYTHON package
which links to the Python library so that the Python interpreter is
embedded in LAMMPS. More details about this process are given below.
There are two ways to invoke a Python function once it has been
defined. One is using the {invoke} keyword. The other is to assign
the function to a "python-style variable"_variable.html defined in
your input script. Whenever the variable is evaluated, it will
execute the Python function to assign a value to the variable. Note
that variables can be evaluated in many different ways within LAMMPS.
They can be substituted for directly in an input script. Or they can
be passed to various commands as arguments, so that the variable is
evaluated during a simulation run.
A broader overview of how Python can be used with LAMMPS is
given in "Section python"_Section_python.html. There is an
examples/python directory which illustrates use of the python
command.
:line
The {func} setting specifies the name of the Python function. The
code for the function is defined using the {file} or {here} keywords
as explained below.
If the {invoke} keyword is used, no other keywords can be used, and a
previous python command must have defined the Python function
referenced by this command. This invokes the Python function with the
previously defined arguments and return value processed as explained
below. You can invoke the function as many times as you wish in your
input script.
The {input} keyword defines how many arguments {N} the Python function
expects. If it takes no arguments, then the {input} keyword should
not be used. Each argument can be specified directly as a value,
e.g. 6 or 3.14159 or abc (a string of characters). The type of each
argument is specified by the {format} keyword as explained below, so
that Python will know how to interpret the value. If the word SELF is
used for an argument it has a special meaning. A pointer is passed to
the Python function which it converts into a reference to LAMMPS
itself. This enables the function to call back to LAMMPS through its
library interface as explained below. This allows the Python function
to query or set values internal to LAMMPS which can affect the
subsequent execution of the input script. A LAMMPS variable can also
be used as an argument, specified as v_name, where "name" is the name
of the variable. Any style of LAMMPS variable can be used, as defined
by the "variable"_variable.html command. Each time the Python
function is invoked, the LAMMPS variable is evaluated and its value is
passed to the Python function.
The {return} keyword is only needed if the Python function returns a
value. The specified {varReturn} must be of the form v_name, where
"name" is the name of a python-style LAMMPS variable, defined by the
"variable"_variable.html command. The Python function can return a
numeric or string value, as specified by the {format} keyword.
As explained on the "variable"_variable.html doc page, the definition
of a python-style variable associates a Python function name with the
variable. This must match the {func} setting for this command. For
exampe these two commands would be self-consistent:
variable foo python myMultiply
python myMultiply return v_foo format f file funcs.py :pre
The two commands can appear in either order in the input script so
long as both are specified before the Python function is invoked for
the first time.
The {format} keyword must be used if the {input} or {return} keyword
is used. It defines an {fstring} with M characters, where M = sum of
number of inputs and outputs. The order of characters corresponds to
the N inputs, followed by the return value (if it exists). Each
character must be one of the following: "i" for integer, "f" for
floating point, "s" for string, or "p" for SELF. Each character
defines the type of the corresponding input or output value of the
Python function and affects the type conversion that is performed
internally as data is passed back and forth between LAMMPS and Python.
Note that it is permissible to use a "python-style
variable"_variable.html in a LAMMPS command that allows for an
equal-style variable as an argument, but only if the output of the
Python function is flagged as a numeric value ("i" or "f") via the
{format} keyword.
Either the {file}, {here}, or {exists} keyword must be used, but only
one of them. These keywords specify what Python code to load into the
Python interpreter. The {file} keyword gives the name of a file,
which should end with a ".py" suffix, which contains Python code. The
code will be immediately loaded into and run in the "main" module of
the Python interpreter. Note that Python code which contains a
function definition does not "execute" the function when it is run; it
simply defines the function so that it can be invoked later.
The {here} keyword does the same thing, except that the Python code
follows as a single argument to the {here} keyword. This can be done
using triple quotes as delimiters, as in the examples above. This
allows Python code to be listed verbatim in your input script, with
proper indentation, blank lines, and comments, as desired. See
"Section 3.2"_Section_commands.html#cmd_2, for an explanation of how
triple quotes can be used as part of input script syntax.
The {exists} keyword takes no argument. It means that Python code
containing the required Python function defined by the {func} setting,
is assumed to have been previously loaded by another python command.
Note that the Python code that is loaded and run must contain a
function with the specified {func} name. To operate properly when
later invoked, the the function code must match the {input} and
{return} and {format} keywords specified by the python command.
Otherwise Python will generate an error.
:line
This section describes how Python code can be written to work with
LAMMPS.
Whether you load Python code from a file or directly from your input
script, via the {file} and {here} keywords, the code can be identical.
It must be indented properly as Python requires. It can contain
comments or blank lines. If the code is in your input script, it
cannot however contain triple-quoted Python strings, since that will
conflict with the triple-quote parsing that the LAMMPS input script
performs.
All the Python code you specify via one or more python commands is
loaded into the Python "main" module, i.e. __main__. The code can
define global variables or statements that are outside of function
definitions. It can contain multiple functions, only one of which
matches the {func} setting in the python command. This means you can
use the {file} keyword once to load several functions, and the
{exists} keyword thereafter in subsequent python commands to access
the other functions previously loaded.
A Python function you define (or more generally, the code you load)
can import other Python modules or classes, it can make calls to other
system functions or functions you define, and it can access or modify
global variables (in the "main" module) which will persist between
successive function calls. The latter can be useful, for example, to
prevent a function from being invoke multiple times per timestep by
different commands in a LAMMPS input script that access the returned
python-style variable associated with the function. For example,
consider this function loaded with two global variables defined
outside the function:
nsteplast = -1
nvaluelast = 0 :pre
def expensive(nstep):
global nsteplast,nvaluelast
if nstep == nsteplast: return nvaluelast
nsteplast = nstep
# perform complicated calculation
nvalue = ...
nvaluelast = nvalue
return nvalue :pre
Nsteplast stores the previous timestep the function was invoked
(passed as an argument to the function). Nvaluelast stores the return
value computed on the last function invocation. If the function is
invoked again on the same timestep, the previous value is simply
returned, without re-computing it. The "global" statement inside the
Python function allows it to overwrite the global variables.
Note that if you load Python code multiple times (via multiple python
commands), you can overwrite previously loaded variables and functions
if you are not careful. E.g. if the code above were loaded twice, the
global variables would be re-initialized, which might not be what you
want. Likewise, if a function with the same name exists in two chunks
of Python code you load, the function loaded second will override the
function loaded first.
It's important to realize that if you are running LAMMPS in parallel,
each MPI task will load the Python interpreter and execute a local
copy of the Python function(s) you define. There is no connection
between the Python interpreters running on different processors.
This implies three important things.
First, if you put a print statement in your Python function, you will
see P copies of the output, when running on P processors. If the
prints occur at (nearly) the same time, the P copies of the output may
be mixed together. Welcome to the world of parallel programming and
debugging.
Second, if your Python code loads modules that are not pre-loaded by
the Python library, then it will load the module from disk. This may
be a bottleneck if 1000s of processors try to load a module at the
same time. On some large supercomputers, loading of modules from disk
by Python may be disabled. In this case you would need to pre-build a
Python library that has the required modules pre-loaded and link
LAMMPS with that library.
Third, if your Python code calls back to LAMMPS (discussed in the
next section) and causes LAMMPS to perform an MPI operation requires
global communication (e.g. via MPI_Allreduce), such as computing the
global temperature of the system, then you must insure all your Python
functions (running independently on different processors) call back to
LAMMPS. Otherwise the code may hang.
:line
Your Python function can "call back" to LAMMPS through its
library interface, if you use the SELF input to pass Python
a pointer to LAMMPS. The mechanism for doing this in your
Python function is as follows:
def foo(lmpptr,...):
from lammps import lammps
lmp = lammps(ptr=lmpptr)
lmp.command('print "Hello from inside Python"')
... :pre
The function definition must include a variable (lmpptr in this case)
which corresponds to SELF in the python command. The first line of
the function imports the Python module lammps.py in the python dir of
the distribution. The second line creates a Python object "lmp" which
wraps the instance of LAMMPS that called the function. The
"ptr=lmpptr" argument is what makes that happen. The thrid line
invokes the command() function in the LAMMPS library interface. It
takes a single string argument which is a LAMMPS input script command
for LAMMPS to execute, the same as if it appeared in your input
script. In this case, LAMMPS should output
Hello from inside Python :pre
to the screen and log file. Note that since the LAMMPS print command
itself takes a string in quotes as its argument, the Python string
must be delimited with a different style of quotes.
"Section 11.7"_Section_python.html#py_7 describes the syntax for how
Python wraps the various functions included in the LAMMPS library
interface.
A more interesting example is in the examples/python/in.python script
which loads and runs the following function from examples/python/funcs.py:
def loop(N,cut0,thresh,lmpptr):
print "LOOP ARGS",N,cut0,thresh,lmpptr
from lammps import lammps
lmp = lammps(ptr=lmpptr)
natoms = lmp.get_natoms() :pre
for i in range(N):
cut = cut0 + i*0.1 :pre
lmp.set_variable("cut",cut) # set a variable in LAMMPS
lmp.command("pair_style lj/cut ${cut}") # LAMMPS command
#lmp.command("pair_style lj/cut %d" % cut) # LAMMPS command option :pre
lmp.command("pair_coeff * * 1.0 1.0") # ditto
lmp.command("run 10") # ditto
pe = lmp.extract_compute("thermo_pe",0,0) # extract total PE from LAMMPS
print "PE",pe/natoms,thresh
if pe/natoms < thresh: return :pre
with these input script commands:
python loop input 4 10 1.0 -4.0 SELF format iffp file funcs.py
python loop invoke :pre
This has the effect of looping over a series of 10 short runs (10
timesteps each) where the pair style cutoff is increased from a value
of 1.0 in distance units, in increments of 0.1. The looping stops
when the per-atom potential energy falls below a threshhold of -4.0 in
energy units. More generally, Python can be used to implement a loop
with complex logic, much more so than can be created using the LAMMPS
"jump"_jump.html and "if"_if.html commands.
Several LAMMPS library functions are called from the loop function.
Get_natoms() returns the number of atoms in the simulation, so that it
can be used to normalize the potential energy that is returned by
extract_compute() for the "thermo_pe" compute that is defined by
default for LAMMPS thermodynamic output. Set_variable() sets the
value of a string variable defined in LAMMPS. This library function
is a useful way for a Python function to return multiple values to
LAMMPS, more than the single value that can be passed back via a
return statement. This cutoff value in the "cut" variable is then
substituted (by LAMMPS) in the pair_style command that is executed
next. Alternatively, the "LAMMPS command option" line could be used
in place of the 2 preceeding lines, to have Python insert the value
into the LAMMPS command string.
IMPORTANT NOTE: When using the callback mechanism just described,
recognize that there are some operations you should not attempt
because LAMMPS cannot execute them correctly. If the Python function
is invoked between runs in the LAMMPS input script, then it should be
OK to invoke any LAMMPS input script command via the library interface
command() or file() functions, so long as the command would work if it
were executed in the LAMMPS input script directly at the same point.
However, a Python function can also be invoked during a run, whenever
an associated LAMMPS variable it is assigned to is evaluted. If the
variable is an input argument to another LAMMPS command (e.g. "fix
setforce"_fix_setforce.html), then the Python function will be invoked
inside the class for that command, in one of its methods that is
invoked in the middle of a timestep. You cannot execute arbitrary
input script commands from the Python function (again, via the
command() or file() functions) at that point in the run and expect it
to work. Other library functions such as those that invoke computes
or other variables may have hidden side effects as well. In these
cases, LAMMPS has no simple way to check that something illogical is
being attempted.
:line
If you run Python code directly on your workstation, either
interactively or by using Python to launch a Python script stored in a
file, and your code has an error, you will typically see informative
error messages. That is not the case when you run Python code from
LAMMPS using an embedded Python interpreter. The code will typically
fail silently. LAMMPS will catch some errors but cannot tell you
where in the Python code the problem occurred. For example, if the
Python code cannot be loaded and run because it has syntax or other
logic errors, you may get an error from Python pointing to the
offending line, or you may get one of these generic errors from
LAMMPS:
Could not process Python file
Could not process Python string :pre
When the Python function is invoked, if it does not return properly,
you will typically get this generic error from LAMMPS:
Python function evaluation failed :pre
Here are three suggestions for debugging your Python code while
running it under LAMMPS.
First, don't run it under LAMMPS, at least to start with! Debug it
using plain Python. Load and invoke your function, pass it arguments,
check return values, etc.
Second, add Python print statements to the function to check how far
it gets and intermediate values it calculates. See the discussion
above about printing from Python when running in parallel.
Third, use Python exception handling. For example, say this statement
in your Python function is failing, because you have not initialized the
variable foo:
foo += 1 :pre
If you put one (or more) statements inside a "try" statement,
like this:
import exceptions
print "Inside simple function"
try:
foo += 1 # one or more statements here
except Exception, e:
print "FOO error:",e :pre
then you will get this message printed to the screen:
FOO error: local variable 'foo' referenced before assignment :pre
If there is no error in the try statements, then nothing is printed.
Either way the function continues on (unless you put a return or
sys.exit() in the except clause).
:line
[Restrictions:]
This command is part of the PYTHON package. It is only enabled if
LAMMPS was built with that package. See the "Making
LAMMPS"_Section_start.html#start_3 section for more info.
Building LAMMPS with the PYTHON package will link LAMMPS with the
Python library on your system. Settings to enable this are in the
lib/python/Makefile.lammps file. See the lib/python/README file for
information on those settings.
If you use Python code which calls back to LAMMPS, via the SELF input
argument explained above, there is an extra step required when
building LAMMPS. LAMMPS must also be built as a shared library and
your Python function must be able to to load the Python module in
python/lammps.py that wraps the LAMMPS library interface. These are
the same steps required to use Python by itself to wrap LAMMPS.
Details on these steps are explained in "Section
python"_Section.python.html. Note that it is important that the
stand-alone LAMMPS executable and the LAMMPS shared library be
consistent (built from the same source code files) in order for this
to work. If the two have been built at different times using
different source files, problems may occur.
As described above, you can use the python command to invoke a Python
function which calls back to LAMMPS through its Python-wrapped library
interface. However you cannot do the opposite. I.e. you cannot call
LAMMPS from Python and invoke the python command to "callback" to
Python and execute a Python function. LAMMPS will generate an error
if you try to do that. Note that we think there actually should be a
way to do that, but haven't yet been able to figure out how to do it
successfully.
[Related commands:]
"shell"_shell.html, "variable"_variable.html
[Default:] none

92
doc/variable.html
View File

@ -17,7 +17,8 @@
</PRE>
<UL><LI>name = name of variable to define
<LI>style = <I>delete</I> or <I>index</I> or <I>loop</I> or <I>world</I> or <I>universe</I> or <I>uloop</I> or <I>string</I> or <I>format</I> or <I>getenv</I> or <I>file</I> or <I>atomfile</I> or <I>equal</I> or <I>atom</I>
<LI>style = <I>delete</I> or <I>index</I> or <I>loop</I> or <I>world</I> or <I>universe</I> or
<I>uloop</I> or <I>string</I> or <I>format</I> or <I>getenv</I> or <I>file</I> or <I>atomfile</I> or <I>python</I> or <I>equal</I> or <I>atom</I>
<PRE> <I>delete</I> = no args
<I>index</I> args = one or more strings
@ -45,6 +46,7 @@
<I>getenv</I> arg = one string
<I>file</I> arg = filename
<I>atomfile</I> arg = filename
<I>python</I> arg = function
<I>equal</I> or <I>atom</I> args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references
numbers = 0.0, 100, -5.4, 2.8e-4, etc
constants = PI
@ -87,6 +89,7 @@ variable b equal xcm(mol1,x)/2.0
variable b equal c_myTemp
variable b atom x*y/vol
variable foo string myfile
variable myPy python increase
variable f file values.txt
variable temp world 300.0 310.0 320.0 ${Tfinal}
variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
@ -116,7 +119,9 @@ command) or used as input to an averaging fix (see the <A HREF = "fix_ave_spatia
ave/spatial</A> and <A HREF = "fix_ave_atom.html">fix ave/atom</A>
commands). Variables of style <I>atomfile</I> can be used anywhere in an
input script that atom-style variables are used; they get their
per-atom values from a file rather than from a formula.
per-atom values from a file rather than from a formula. Variables can
be hooked to Python functions using code you provide, so that the
variable gets its value from the evaluation of the Python code.
</P>
<P>IMPORTANT NOTE: As discussed in <A HREF = "Section_commands.html#cmd_2">Section
3.2</A> of the manual, an input script can
@ -138,11 +143,31 @@ different values when it is evaluated at different times during a
simulation.
</P>
<P>IMPORTANT NOTE: When the input script line is encountered that defines
a variable of style <I>equal</I> or <I>atom</I> that contains a formula, the
formula is NOT immediately evaluated and the result stored. See the
discussion below about "Immediate Evaluation of Variables" if you want
to do this. This is also true of the <I>format</I> style variable
since it evaluates another variable when it is invoked.
a variable of style <I>equal</I> or <I>atom</I> or <I>python</I> that contains a
formula or Python code, the formula is NOT immediately evaluated and
the result stored. See the discussion below about "Immediate
Evaluation of Variables" if you want to do this. This is also true of
the <I>format</I> style variable since it evaluates another variable when
it is invoked.
</P>
<P>IMPORTANT NOTE: Variables of style <I>equal</I> and <I>atom</I> can be used as
inputs to various other LAMMPS commands which evaluate their formulas
as needed, e.g. at different timesteps during a <A HREF = "run.html">run</A>.
Variables of style <I>python</I> can be used in place of an equal-style
variable so long as the associated Python function, as defined by the
<A HREF = "python.html">python</A> command, returns a numeric value. Thus any
command that states it can use an equal-style variable as an argument,
can also use such a python-style variable. This means that when the
LAMMPS command evaluates the variable, the Python function will be
executed.
</P>
<P>When the input script line is encountered that defines
a variable of style <I>equal</I> or <I>atom</I> or <I>python</I> that contains a
formula or Python code, the formula is NOT immediately evaluated and
the result stored. See the discussion below about "Immediate
Evaluation of Variables" if you want to do this. This is also true of
the <I>format</I> style variable since it evaluates another variable when
it is invoked.
</P>
<P>IMPORTANT NOTE: When a variable command is encountered in the input
script and the variable name has already been specified, the command
@ -155,12 +180,12 @@ means that using the <A HREF = "Section_start.html#start_7">command-line switch<
script.
</P>
<P>There are two exceptions to this rule. First, variables of style
<I>string</I>, <I>getenv</I>, <I>equal</I> and <I>atom</I> ARE redefined each time the
command is encountered. This allows these style of variables to be
redefined multiple times in an input script. In a loop, this means
the formula associated with an <I>equal</I> or <I>atom</I> style variable can
change if it contains a substitution for another variable, e.g. $x or
v_x.
<I>string</I>, <I>getenv</I>, <I>equal</I>, <I>atom</I>, and <I>python</I> ARE redefined each
time the command is encountered. This allows these style of variables
to be redefined multiple times in an input script. In a loop, this
means the formula associated with an <I>equal</I> or <I>atom</I> style variable
can change if it contains a substitution for another variable, e.g. $x
or v_x.
</P>
<P>Second, as described below, if a variable is iterated on to the end of
its list of strings via the <A HREF = "next.html">next</A> command, it is removed
@ -202,13 +227,15 @@ variable a delete
</PRE>
<HR>
<P>This section describes how various variable styles are defined and
what they store. Many of the styles store one or more strings. Note
that a single string can contain spaces (multiple words), if it is
enclosed in quotes in the variable command. When the variable is
substituted for in another input script command, its returned string
will then be interpreted as multiple arguments in the expanded
command.
<P>This section describes how all the various variable styles are defined
and what they store. Except for the <I>equal</I> and <I>atom</I> styles,
which are explaine in the next section.
</P>
<P>Many of the styles store one or more strings. Note that a single
string can contain spaces (multiple words), if it is enclosed in
quotes in the variable command. When the variable is substituted for
in another input script command, its returned string will then be
interpreted as multiple arguments in the expanded command.
</P>
<P>For the <I>index</I> style, one or more strings are specified. Initially,
the 1st string is assigned to the variable. Each time a
@ -338,6 +365,31 @@ will be assigned to that atom. IDs can be listed in any order.
for all atoms is first set to 0.0. Thus values for atoms whose ID
does not appear in the set, will remain 0.0.
</P>
<P>For the <I>python</I> style a Python function name is provided. This needs
to match a function name specified in a <A HREF = "python.html">python</A> command
which returns a value to this variable as defined by its <I>return</I>
keyword. For exampe these two commands would be self-consistent:
</P>
<PRE>variable foo python myMultiply
python myMultiply return v_foo format f file funcs.py
</PRE>
<P>The two commands can appear in either order so long as both are
specified before the Python function is invoked for the first time.
</P>
<P>Each time the variable is evaluated, the associated Python function is
invoked, and the value it returns is also returned by the variable.
Since the Python function can use other LAMMPS variables as input, or
query interal LAMMPS quantities to perform its computation, this means
the variable can return a different value each time it is evaluated.
</P>
<P>The type of value stored in the variable is determined by the <I>format</I>
keyword of the <A HREF = "python.html">python</A> command. It can be an integer
(i), floating point (f), or string (s) value. As mentioned above, if
it is a numeric value (integer or floating point), then the
python-style variable can be used in place of an equal-style variable
anywhere in an input script, e.g. as an argument to another command
that allows for equal-style variables.
</P>
<HR>
<P>For the <I>equal</I> and <I>atom</I> styles, a single string is specified which

92
doc/variable.txt
View File

@ -13,7 +13,8 @@ variable command :h3
variable name style args ... :pre
name = name of variable to define :ulb,l
style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {string} or {format} or {getenv} or {file} or {atomfile} or {equal} or {atom} :l
style = {delete} or {index} or {loop} or {world} or {universe} or
{uloop} or {string} or {format} or {getenv} or {file} or {atomfile} or {python} or {equal} or {atom} :l
{delete} = no args
{index} args = one or more strings
{loop} args = N
@ -40,6 +41,7 @@ style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {st
{getenv} arg = one string
{file} arg = filename
{atomfile} arg = filename
{python} arg = function
{equal} or {atom} args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references
numbers = 0.0, 100, -5.4, 2.8e-4, etc
constants = PI
@ -81,6 +83,7 @@ variable b equal xcm(mol1,x)/2.0
variable b equal c_myTemp
variable b atom x*y/vol
variable foo string myfile
variable myPy python increase
variable f file values.txt
variable temp world 300.0 310.0 320.0 $\{Tfinal\}
variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
@ -110,7 +113,9 @@ command) or used as input to an averaging fix (see the "fix
ave/spatial"_fix_ave_spatial.html and "fix ave/atom"_fix_ave_atom.html
commands). Variables of style {atomfile} can be used anywhere in an
input script that atom-style variables are used; they get their
per-atom values from a file rather than from a formula.
per-atom values from a file rather than from a formula. Variables can
be hooked to Python functions using code you provide, so that the
variable gets its value from the evaluation of the Python code.
IMPORTANT NOTE: As discussed in "Section
3.2"_Section_commands.html#cmd_2 of the manual, an input script can
@ -132,11 +137,31 @@ different values when it is evaluated at different times during a
simulation.
IMPORTANT NOTE: When the input script line is encountered that defines
a variable of style {equal} or {atom} that contains a formula, the
formula is NOT immediately evaluated and the result stored. See the
discussion below about "Immediate Evaluation of Variables" if you want
to do this. This is also true of the {format} style variable
since it evaluates another variable when it is invoked.
a variable of style {equal} or {atom} or {python} that contains a
formula or Python code, the formula is NOT immediately evaluated and
the result stored. See the discussion below about "Immediate
Evaluation of Variables" if you want to do this. This is also true of
the {format} style variable since it evaluates another variable when
it is invoked.
IMPORTANT NOTE: Variables of style {equal} and {atom} can be used as
inputs to various other LAMMPS commands which evaluate their formulas
as needed, e.g. at different timesteps during a "run"_run.html.
Variables of style {python} can be used in place of an equal-style
variable so long as the associated Python function, as defined by the
"python"_python.html command, returns a numeric value. Thus any
command that states it can use an equal-style variable as an argument,
can also use such a python-style variable. This means that when the
LAMMPS command evaluates the variable, the Python function will be
executed.
When the input script line is encountered that defines
a variable of style {equal} or {atom} or {python} that contains a
formula or Python code, the formula is NOT immediately evaluated and
the result stored. See the discussion below about "Immediate
Evaluation of Variables" if you want to do this. This is also true of
the {format} style variable since it evaluates another variable when
it is invoked.
IMPORTANT NOTE: When a variable command is encountered in the input
script and the variable name has already been specified, the command
@ -149,12 +174,12 @@ means that using the "command-line switch"_Section_start.html#start_7
script.
There are two exceptions to this rule. First, variables of style
{string}, {getenv}, {equal} and {atom} ARE redefined each time the
command is encountered. This allows these style of variables to be
redefined multiple times in an input script. In a loop, this means
the formula associated with an {equal} or {atom} style variable can
change if it contains a substitution for another variable, e.g. $x or
v_x.
{string}, {getenv}, {equal}, {atom}, and {python} ARE redefined each
time the command is encountered. This allows these style of variables
to be redefined multiple times in an input script. In a loop, this
means the formula associated with an {equal} or {atom} style variable
can change if it contains a substitution for another variable, e.g. $x
or v_x.
Second, as described below, if a variable is iterated on to the end of
its list of strings via the "next"_next.html command, it is removed
@ -196,13 +221,15 @@ variable a delete :pre
:line
This section describes how various variable styles are defined and
what they store. Many of the styles store one or more strings. Note
that a single string can contain spaces (multiple words), if it is
enclosed in quotes in the variable command. When the variable is
substituted for in another input script command, its returned string
will then be interpreted as multiple arguments in the expanded
command.
This section describes how all the various variable styles are defined
and what they store. Except for the {equal} and {atom} styles,
which are explaine in the next section.
Many of the styles store one or more strings. Note that a single
string can contain spaces (multiple words), if it is enclosed in
quotes in the variable command. When the variable is substituted for
in another input script command, its returned string will then be
interpreted as multiple arguments in the expanded command.
For the {index} style, one or more strings are specified. Initially,
the 1st string is assigned to the variable. Each time a
@ -332,6 +359,31 @@ IMPORTANT NOTE: Every time a set of per-atom lines is read, the value
for all atoms is first set to 0.0. Thus values for atoms whose ID
does not appear in the set, will remain 0.0.
For the {python} style a Python function name is provided. This needs
to match a function name specified in a "python"_python.html command
which returns a value to this variable as defined by its {return}
keyword. For exampe these two commands would be self-consistent:
variable foo python myMultiply
python myMultiply return v_foo format f file funcs.py :pre
The two commands can appear in either order so long as both are
specified before the Python function is invoked for the first time.
Each time the variable is evaluated, the associated Python function is
invoked, and the value it returns is also returned by the variable.
Since the Python function can use other LAMMPS variables as input, or
query interal LAMMPS quantities to perform its computation, this means
the variable can return a different value each time it is evaluated.
The type of value stored in the variable is determined by the {format}
keyword of the "python"_python.html command. It can be an integer
(i), floating point (f), or string (s) value. As mentioned above, if
it is a numeric value (integer or floating point), then the
python-style variable can be used in place of an equal-style variable
anywhere in an input script, e.g. as an argument to another command
that allows for equal-style variables.
:line
For the {equal} and {atom} styles, a single string is specified which