Aspherix vs LIGGGHTS ® 4.X - syntax changes

With the move to Aspherix®, we have introduced a novel input script syntax to facilitate the creation of input scripts by (a) shortening them and (b) increasing readability. This document outlines the new syntax, but is not intended as a comprehensive manual. The old syntax will be referred to as LIGGGHTS ® syntax throughout this document.

Note

Aspherix® still fully supports the old LIGGGHTS ® 4.x input script syntax. Also, functionalities not yet covered by the new Aspherix® syntax can be accessed through the respective LIGGGHTS ® commands.

Basic concepts 

Vectors and Lists

Two new syntax elements are used in the Aspherix® input script syntax: vectors and lists.

Three comma separated numbers between round brackets, such as (0.,2.5,-1), form a vector. Vectors are only used when a parameter represents an actual vector in $\mathbb{R}^3$ , such as a point or a velocity/force vector. The individual entries can be space-separated, so (1,2,3) and ( 1, 2, 3 ) are parsed as the same vector.

An arbitrary number of comma-separated entries between curly braces, for example {steel, glass, rubber, limestone} or {0.3,0.1,0.2,0.15,0.35}, is considered a list. Several commands require lists with different entries, such as numbers, strings or percentages. Again, spaces between the list entries do not matter.

Command IDs

Most new commands have an id keyword. This keyword is usually optional, and only required if the command is either required by some other commands (for example in the particle distributions) or to be altered (via modify_command) or disabled (via disable_command). A possible sequence could be

# define output
write_to_file [...] id output

[do simulation tasks]

# don't need output any more
disable_command id output

[go on with simulation]

Domain creation and basic setup 

The first couple of lines of any input script usually contain domain definition and a few general setup commands. This first section of a typical LIGGGHTS ® input script might look like this:

atom_style    granular
atom_modify   map array
boundary      f f f
newton        off

communicate   single vel yes

units         si

region        domain block -0.5 0.1 -0.2 0.2 -0.4 0.15 units box
create_box    1 domain

neighbor      0.002 bin
neigh_modify  delay 0

This defines the use of spherical particles, defines fixed boundaries, sets a few communication options, sets the units to SI, creates the simulation domain, and defines a neighbor list using a skin of $0.002 \, \mathrm{m}$ .

Using the new Aspherix® syntax, this shortens to three commands:

particle_shape sphere
simulation_domain low (-0.5, -0.2, -0.4) high (0.1, 0.2, 0.15)
neighbor_list skin_size 0.002

See particle_shape, simulation_domain and neighbor_list for details on the individual commands.

Load balancing 

RCB load balancing in LIGGGHTS ® was available through comm_style command and fix balance:

comm_style tiled
[...]
fix loadbalancing all balance 1000 1.1 rcb

RCB load balancing can now be activated through the enable_loadbalancing command, without the need to set the comm_style:

enable_loadbalancing check_every_time 0.01 target_imbalance 1.1

Note that the timestep number (1000 in the example above) has been replaced with an interval in time units (check_every_time).

Note

“brick” style load balancing is still available through fix balance, but in most cases it is less efficient. It may outperform “tiled” in situations where (a) the number of processors used is not a power of 2 and (b) particle distribution in the domain is rather homogeneous.

Material Properties 

The definition of material properties has been redesigned from scratch to provide a more human-readable interface. In the old syntax, materials were defined via atom types, and properties were mainly set through fix property/global:

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.3
fix m4 all property/global coefficientFriction peratomtypepair 1 0.5
fix m5 all property/global k_finnie peratomtypepair 1 1.0

which could lead to very long and convoluted commands in case of many atom types. Below is an example with four atom types:

fix m4 all property/global coefficientFriction 4 &
        0.1 0.2 0.3 0.4 &
        0.2 0.2 0.3 0.4 &
        0.3 0.3 0.3 0.4 &
        0.4 0.4 0.4 0.4

The new syntax allows to (a) assign names to materials, and (b) separately define material properties and material interaction properties:

materials {m1,m2}
material_properties m1 &
                    density 2500 &
                    youngsModulus 5e6 poissonsRatio 0.45 &
                    coefficientRestitution 0.3 coefficientFriction 0.5 &
                    k_finnie 1
material_properties m2 &
                    density 4000 &
                    youngsModulus 2e7 poissonsRatio 0.3 &
                    coefficientRestitution 0.6 coefficientFriction 0.1 &
                    k_finnie 0.6
material_interaction_properties m1 m2 &
                                coefficientRestitution 0.7 coefficientFriction 0.4 &
                                k_finnie 0.8

Material properties previously defined as peratomtype, such as youngsModulus, are now defined through material_properties. Most importantly, the density, which was defined in the fix particletemplate commands, is now part of material_properties. Properties previously defined as peratomtypepair such as coefficientFriction, appear in both the material_properties and material_interaction_properties command. The value from material_properties is used when two particles of the same material interact, while the value from material_interaction_properties is used for interactions of particles of different materials. This allows to quickly modify the materials used: if the user decides to add a third material, m3, to the example above, he or she can do so by

changing the materials command to materials {m1,m2,m3}
adding material_properties m3 [...]
adding material_interaction_properties m1 m3 [...] and material_interaction_properties m2 m3 [...]

while leaving the already defined properties unchanged.

Particle Distributions 

LIGGGHTS ® used fixes to define particle templates and distributions, for example

fix pts1 all particletemplate/sphere 15485863 atom_type 1 density constant 2500 radius constant 0.0015
fix pts2 all particletemplate/sphere 15485867 atom_type 1 density constant 2500 radius constant 0.0025
fix pdd1 all particledistribution/discrete 32452843  2 pts1 0.3 pts2 0.7

This has been changed to

particle_template id smallParticles material m1 radius 1.5e-3
particle_template id largeParticles material m1 radius 2.5e-3
particle_distribution id pdd1 templates {smallParticles,largeParticles} fractions {0.3, 0.7}

The most prominent difference is that density is no longer given in the template, but in the material_properties command. Additionally, LIGGGHTS ® required seeds for random generators, which are now assigned default values. For more details, please see particle_template and particle_distribution.

Note

Due to changing seeds, simulations converted from LIGGGHTS ® to Aspherix® style might not be identical. They will still feature equivalent behavior on a macroscopic level. If identical results are important, consider setting seeds manually. See the documentation individual commands for details.

Contact models 

A list of available contact models can be found here.

Particles

In LIGGGHTS ®, the contact model was defined by the following two lines:

pair_style  gran model hertz tangential history
pair_coeff  * *

In Aspherix®, this is reduced to a single line:

particle_contact_model normal hertz tangential history

For more information, see particle_contact_model.

Walls

In LIGGGHTS ®, the wall contact model was defined individually for each fix wall/gran:

fix granwalls all wall/gran model hertz tangential history mesh n_meshes 1 meshes cad
fix zwall all wall/gran model hooke tangential history primitive type 1 zplane 0.15

In the new syntax, the command wall_contact_model sets the contact model for all walls in the simulation:

wall_contact_model normal hertz tangential history

Note

It is currently not possible to use different contact models for individual walls using the new syntax. If you really need this, consider either

using a workaround: eg. you have several walls, and want cohesion on one but not on the other. In that case, add a new material and set cohesion properties of that material to zero
resorting to old syntax

Walls (meshed and primitive) and mesh modules 

In the old LIGGGHTS ® style, mesh walls were defined through a combination of fix mesh/surface(/stress) and fix wall/gran, while primitive walls were defined by single fix wall/gran commands:

fix cad all mesh/surface/stress file meshes/simple_chute.stl type 1
fix xwall all wall/gran model hertz tangential history primitive type 1 xplane -0.1

fix granwalls all wall/gran model hertz tangential history mesh n_meshes 1 meshes cad

In Aspherix®, the same can be achieved with the following commands:

mesh id cad file meshes/simple_chute.stl material m1 solid yes
primitive_wall id xwall material steel type plane normal_axis x offset -0.1

wall_contact_model normal hertz tangential history

The solid yes keyword in the mesh command indicates that the mesh is used as wall. The command primitive_wall is used to define a primitive wall. The contact model combination specified in wall_contact_model is valid for all walls, meshed and primitive. Note that all meshes now evaluate stresses by default.

Mesh Modules

Several mesh modules can be used to add functionality to mesh walls. In the old LIGGGHTS ® syntax, some mesh modules were activated through the fix style, while others were initialized through keywords appended to the respective fix command. In Aspherix®, this has been unified in the mesh_module command. For example, to activate the Finnie wear model, use

mesh_module wear id wear_model model finnie
mesh id cad file meshes/simple_chute.stl material m1 mesh_modules {wear_model} solid yes

A list of available mesh modules can be found in the command index.

Note

Mesh motion is now available through mesh_module motion, replacing the old fix move/mesh.

Particle Insertion 

In the LIGGGHTS ® syntax, particle insertion was performed through various fix commands, the two most important ones being fix insert/pack and fix insert/stream:

fix ins all insert/pack seed 123457 distributiontemplate pdd1 insert_every once overlapcheck yes volumefraction_region 0.3 region mysphere ntry_mc 10000
fix ins all insert/stream seed 123457 distributiontemplate pdd1 nparticles 5000 vel constant 0. -0.5 -2. particlerate 1000 overlapcheck yes insertion_face ins_mesh extrude_length 0.6

In Aspherix®, this is unified in the insertion command:

insertion id ins mode pack particle_distribution pdd1 insert_every_time once region mysphere volume_fraction 0.3
insertion id ins mode stream particle_distribution pdd1 target_particle_count 5000 particlerate 1000 all_in no velocity constant (0, -0.5, -2) insertion_face ins_mesh extrude_length 0.6

Note

Due to changing seeds, simulations converted from LIGGGHTS ® to Aspherix® style might not be identical. They will still feature equivalent behavior on a macroscopic level. If identical results are important, consider setting seeds manually. See the documentation individual commands for details.

Timestep, running a simulation 

The timestep is now defined using the simulation_timestep command. This was done to distinguish the simulation timestep from other timesteps that can be defined, such as write_output_timestep and write_to_terminal_timestep (to be explained below).

In the old syntax, the run command was the working horse for actual execution of a simulation. Commands such as

run 1000
run 1200 upto

were used to define for how long a simulation was run. In the new syntax, this is done using the simulate command. Unlike run, simulate accepts both timestep numbers and physical time. For the latter, the number of timesteps is computed by dividing the specified time by the current simulation timestep. This has the advantage that simulate commands do not need to be updated if the simulation timestep changes. Example commands are:

simulate time 0.3          #simulates 0.3 seconds
simulate target_time 0.4   #simulates until 0.4 seconds are elapsed

It is still possible to pass timestep numbers to the simulate command. The following two commands are equivalent to the run commands above:

simulate time_steps 1000
simulate target_time_steps 1200

Simulation output 

The old LIGGGHTS ® syntax had many different ways of creating simulation output, both to the terminal and to files. These were spread over several commands, most notably dump (including various dump styles), status, print and fix print. Simulation output is probably the part where the biggest changes from LIGGGHTS ® to Aspherix® happened.

output_settings

In the new syntax, many of the functionalities enabled by those commands are aggregated in the output_settings command. This command, if issued without any keywords, enables sensible default settings for both terminal output and writing of simulation snapshots. See the documentation of output_settings for details on this default.

Output time steps

In the old syntax, the output frequency had to be given to each individual output command. In Aspherix®, the output frequency can be set in time units using the write_output_timestep and write_to_terminal_timestep:

write_output_timestep 0.01
write_to_terminal_timestep 0.002

Individual output commands use these values, or can override it.

output_settings also defines a default for the status output, but the LIGGGHTS ® command status is still used to define custom status output.

Aggregated simulation output

The calculate command provides simple writing of selected aggregated quantities to files. For example, the command

calculate center_of_mass

creates an output file data_center_of_mass.txt which contains the COM of all particles in the simulation, computed every write_output_timestep. For available quantities, see the documentation of calculate.

To write arbitrary values to a file periodically, LIGGGHTS ® offered the fix print command:

fix marker all print 100 "Coords of marker particle = $x $y $z" file coord.txt

The same can now be achieved using the command

write_to_file string "Coords of marker particle = $x $y $z" file coord.txt id marker write_every_time 1e-4

Note that in the above example, the writing interval has been set explicitly.

Selected physics models 

Several physics models that were made available through fix styles can now be called via individual commands:

LIGGGHTS ®-style fix	Aspherix®-style command
fix buoyancy	enable_buoyancy
fix gravity	enable_gravity
fix heat/gran	enable_heat_transfer
fix dragforce/field	enable_one_way_coupling

The “command” command 

The command command is a general-purpose interface to create LIGGGHTS ®-style fixes and computes. It mainly increases readability in creation of these commands. For example,

command id f1 particle_group powder style powder/update alpha_relaxation_time 0.5

replaces

fix f1 powder powder/update alpha_relaxation_time 0.5