"Previous Section"_Section_start.html - "LIGGGHTS(R)-PUBLIC WWW Site"_liws - "LIGGGHTS(R)-PUBLIC Documentation"_ld - "LIGGGHTS(R)-PUBLIC Commands"_lc - "Next Section"_Section_commands.html :c

:link(liws,http://www.cfdem.com)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

3. Input Script :h3

This section describes how a LIGGGHTS(R)-PUBLIC input script is formatted and the
input script commands used to define a LIGGGHTS(R)-PUBLIC simulation.

<!-- RST

.. contents:: 
		:local:
		:depth: 1
   
END_RST -->

<!-- HTML_ONLY -->
3.1 "LIGGGHTS(R)-PUBLIC input script"_#inp_1
3.2 "Parsing rules"_#inp_2
3.3 "Input script structure"_#inp_3
3.4 "An example input script"_#inp_4  :all(b)
<!--END_HTML_ONLY -->

:line
:line

3.1 LIGGGHTS(R)-PUBLIC input script :link(inp_1),h4

LIGGGHTS(R)-PUBLIC executes by reading commands from a input script (text file),
one line at a time.  When the input script ends, LIGGGHTS(R)-PUBLIC exits.  Each
command causes LIGGGHTS(R)-PUBLIC to take some action.  It may set an internal
variable, read in a file, or run a simulation.  Most commands have
default settings, which means you only need to use the command if you
wish to change the default.

In many cases, the ordering of commands in an input script is not
important.  However the following rules apply:

(1) LIGGGHTS(R)-PUBLIC does not read your entire input script and then perform a
simulation with all the settings.  Rather, the input script is read
one line at a time and each command takes effect when it is read.
Thus this sequence of commands:

timestep 0.5
run      100
run      100 :pre

does something different than this sequence:

run      100
timestep 0.5
run      100 :pre

In the first case, the specified timestep (0.5 fmsec) is used for two
simulations of 100 timesteps each.  In the 2nd case, the default
timestep (1.0 fmsec) is used for the 1st 100 step simulation and a 0.5
fmsec timestep is used for the 2nd one.

(2) Some commands are only valid when they follow other commands.  For
example you cannot set the temperature of a group of atoms until atoms
have been defined and a group command is used to define which atoms
belong to the group.

(3) Sometimes command B will use values that can be set by command A.
This means command A must precede command B in the input script if it
is to have the desired effect.  For example, the
"read_data"_read_data.html command initializes the system by setting
up the simulation box and assigning atoms to processors.  If default
values are not desired, the "processors"_processors.html and
"boundary"_boundary.html commands need to be used before read_data to
tell LIGGGHTS(R)-PUBLIC how to map processors to the simulation box.

Many input script errors are detected by LIGGGHTS(R)-PUBLIC and an ERROR or
WARNING message is printed.  "This section"_Section_errors.html gives
more information on what errors mean.  The documentation for each
command lists restrictions on how the command can be used.

:line

3.2 Parsing rules :link(inp_2),h4

Each non-blank line in the input script is treated as a command.
LIGGGHTS(R)-PUBLIC commands are case sensitive.  Command names are lower-case, as
are specified command arguments.  Upper case letters may be used in
file names or user-chosen ID strings.

Here is how each line in the input script is parsed by LIGGGHTS(R)-PUBLIC:

(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.

(2) All characters from the first "#" character onward are treated as
comment and discarded.  See an exception in (6).  Note that a
comment after a trailing "&" character will prevent the command from
continuing on the next line.  Also note that for multi-line commands a
single leading "#" will comment out the entire command.

(3) The line is searched repeatedly for $ characters, which indicate
variables that are replaced with a text string.  See an exception in
(6).

If the $ is followed by curly brackets, then the variable name is the
text inside the curly brackets.  If no curly brackets follow the $,
then the variable name is the single character immediately following
the $.  Thus $\{myTemp\} and $x refer to variable names "myTemp" and
"x".

If the $ is followed by parenthesis, then the text inside the
parenthesis is treated as an "immediate" variable and evaluated as an
"equal-style variable"_variable.html.  This is a way to use numeric
formulas in an input script without having to assign them to variable
names.  For example, these 3 input script lines:

variable X equal (xlo+xhi)/2+sqrt(v_area)
region 1 block $X 2 INF INF EDGE EDGE
variable X delete :pre

can be replaced by

region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE :pre

so that you do not have to define (or discard) a temporary variable X.

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
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
"equal-style variable"_variable.html.

See the "variable"_variable.html command for more details of how
strings are assigned to variables and evaluated, and how they can be
used in input script commands.

(4) The line is broken into "words" separated by whitespace (tabs,
spaces).  Note that words can thus contain letters, digits,
underscores, or punctuation characters.

(5) The first word is the command name.  All successive words in the
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.  E.g.

print "Volume = $v"
print 'Volume = $v'
if "${steps} > 1000" then quit :pre

The quotes are removed when the single argument 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).

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
for those commands for examples.  Only one of level of nesting is
allowed, but that should be sufficient for most use cases.

:line

3.3 Input script structure :h4,link(inp_3)

This section describes the structure of a typical LIGGGHTS(R)-PUBLIC input script.
The "examples" directory in the LIGGGHTS(R)-PUBLIC distribution contains many
sample input scripts; the corresponding problems are discussed in
"Section_example"_Section_example.html, and animated on the "LIGGGHTS(R)-PUBLIC
WWW Site"_liws.

A LIGGGHTS(R)-PUBLIC input script typically has 4 parts:

Initialization
Atom/particle definition and insertion
Settings
Run a simulation :ol

The last 2 parts can be repeated as many times as desired.  I.e. run a
simulation, change some settings, run some more, etc.  Each of the 4
parts is now described in more detail.  Remember that almost all the
commands need only be used if a non-default value is desired.

(1) Initialization

Set parameters that need to be defined before atoms/particles are created or
read-in from a file.

The relevant commands are "units"_units.html,
"dimension"_dimension.html, "newton"_newton.html,
"processors"_processors.html, "boundary"_boundary.html,
"atom_style"_atom_style.html, "atom_modify"_atom_modify.html.

If force-field parameters appear in the files that will be read, these
commands tell LIGGGHTS(R)-PUBLIC what kinds of force fields are being used:
"pair_style"_pair_style.html, "bond_style"_bond_style.html,
"fix wall/gran"_fix_wall_gran.html .

Granular walls typically require meshes to be used. See
"fix mesh/surface"_fix_mesh_surface.html for details.

(2) Atom/particle definition and insertion

There are 3 ways to define atoms in LIGGGHTS(R)-PUBLIC.  Read them in from a data
or restart file via the "read_data"_read_data.html or
"read_restart"_read_restart.html commands. Or create atoms on a lattice
using these commands: "lattice"_lattice.html,
"region"_region.html, "create_box"_create_box.html,
"create_atoms"_create_atoms.html.

However, the most common way to insert granular particles is
to use one of the fix insert/* commands: "fix insert/pack"_fix_insert_pack.html,
"fix insert/stream"stream.html, "fix insert/rate/region"_fix_insert_rate/region.html

Before these insertion commands can be used, particle distributions
("fix particledistribution/discrete"_fix_particledistribution_discrete.hmtl)
are built up using particle templates. For spherical particles, such
particle templates are defined using "fix particletemplate/sphere"_fix_particletemplate_sphere.html.

(3) Settings

Once atoms are defined, a variety of settings can be specified:
simulation parameters, output options, etc.

Material parameters and force field coefficients are set by these commands
"fix property/global"_fix_property_global.hmtl,
or "pair_coeff"_pair_coeff.html, "bond_coeff"_bond_coeff.html.

Various simulation parameters are set by these commands:
"neighbor"_neighbor.html, "neigh_modify"_neigh_modify.html,
"group"_group.html, "timestep"_timestep.html, "region"_region.html,
"reset_timestep"_reset_timestep.html, "run_style"_run_style.html,

Fixes impose a variety of boundary conditions, time integration, and
diagnostic options.  The "fix"_fix.html command comes in many flavors.

Various computations can be specified for execution during a
simulation using the "compute"_compute.html,
"compute_modify"_compute_modify.html, and "variable"_variable.html
commands.

Output options are set by the "thermo"_thermo.html, "dump"_dump.html,
and "restart"_restart.html commands.

(4) Run a simulation

A simulation is run using the "run"_run.html command.

:line

3.4 An example input script :link(cmd_4),h4

This shows an example input script for a LIGGGHTS(R)-PUBLIC simulation.

#Contact model example
atom_style   granular
atom_modify  map array
boundary     m m m
newton       off
communicate	 single vel yes
units        si
region       reg block -0.05 0.05 -0.05 0.05 0. 0.15 units box
create_box   1 reg
neighbor     0.002 bin
neigh_modify delay 0
#Material properties required for pair style
fix          m1 all property/global youngsModulus peratomtype 5.e6
fix          m2 all property/global poissonsRatio peratomtype 0.45
fix          m3 all property/global coefficientRestitution peratomtypepair 1 0.95
fix          m4 all property/global coefficientFriction peratomtypepair 1 0.05
pair_style   gran model hertz tangential history
pair_coeff	 * *
timestep     0.00001
fix          gravi all gravity 9.81 vector 0.0 0.0 -1.0
fix          zwalls1 all wall/gran model hertz tangential history primitive type 1 zplane 0.0
fix          zwalls2 all wall/gran model hertz tangential history primitive type 1 zplane 0.15
fix          cylwalls all wall/gran model hertz tangential history primitive type 1 zcylinder 0.05 0. 0.
#region of insertion
region       bc cylinder z 0. 0. 0.045 0.00 0.15 units box
#particle distributions
fix          pts1 all particletemplate/sphere 12345787 1 density constant 2500 radius constant 0.0025
fix          pdd1 all particledistribution/discrete 17903  1 pts1 1.0
fix          ins all insert/pack seed 123457 distributiontemplate pdd1 vel constant 0. 0. -0.5 &
             insert_every once overlapcheck yes all_in yes particles_in_region 1800 region bc
#apply nve integration to all particles
fix          integr all nve/sphere
#output settings, include total thermal energy
compute         rke all erotate/sphere
thermo_style    custom step atoms ke c_rke vol
thermo          1000
thermo_modify   lost ignore norm no
compute_modify  thermo_temp dynamic yes
dump            dmp all custom 800 post/dump*.newModels id type x y z ix iy iz vx vy vz fx fy fz omegax omegay omegaz radius
#insert particles and run
run             5000 :pre