Merge pull request #478 from akohlmey/add-python-source-cmd

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.

and callbacks to LAMMPS. See "fix python"_fix_python.html to learn about

possibilities to execute Python code during each time step.

To run pure Python code from LAMMPS, you only need to build LAMMPS

with the PYTHON package installed:

"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

fix python command :h3

[Syntax:]

fix ID group-ID python N callback function_name :pre

ID, group-ID are ignored by this fix :ulb,l

python = style name of this fix command :l

N = execute every N steps :l

callback = {post_force} or {end_of_step} :l

  {post_force} = callback after force computations on atoms every N time steps

  {end_of_step} = callback after every N time steps :pre

:ule

[Examples:]

python post_force_callback here """

from lammps import lammps :pre

def post_force_callback(lammps_ptr, vflag):

    lmp = lammps(ptr=lammps_ptr)

    # access LAMMPS state using Python interface

""" :pre

python end_of_step_callback here """

def end_of_step_callback(lammps_ptr):

    lmp = lammps(ptr=lammps_ptr)

    # access LAMMPS state using Python interface

""" :pre

fix pf  all python 50 post_force post_force_callback

fix eos all python 50 end_of_step end_of_step_callback :pre

[Description:]

This fix allows you to call a Python function during a simulation run.

The callback is either executed after forces have been applied to atoms

or at the end of every N time steps.

Callback functions must be declared in the global scope of the

active Python interpreter. This can either be done by defining it

inline using the python command or by importing functions from other

Python modules. If LAMMPS is driven using the library interface from

Python, functions defined in the driving Python interpreter can also

be executed.

Each callback is given a pointer object as first argument. This can be

used to initialize an instance of the lammps Python interface, which

gives access to the LAMMPS state from Python.

IMPORTANT NOTE: While you can access the state of LAMMPS via library functions

from these callbacks, trying to execute input script commands will in the best

case not work or in the worst case result in undefined behavior.

[Restrictions:]

This fix 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.

[Related commands:]

"python command"_python.html

   fix_press_berendsen

   fix_print

   fix_property_atom

   fix_python

   fix_qbmsst

   fix_qeq

   fix_qeq_comb

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 {length} or {file} or {here} or {exists}

keyword = {invoke} or {input} or {return} or {format} or {length} or {file} or {here} or {exists} or {source}

  {invoke} arg = none = invoke the previously defined Python function

  {input} args = N i1 i2 ... iN

    N = # of inputs to function

  {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

  {exists} arg = none = Python code has been loaded by previous python command

  {source} arg = {filename} or {inline}

    filename = file of Python code which will be executed immediately

    inline = one or more lines of Python code which will be executed immediately

             must be a single argument, typically enclosed between triple quotes

:pre

:ule

[Examples:]

[Description:]

Define a Python function or execute a previously defined function.

Define a Python function or execute a previously defined function or

execute some arbitrary python code.

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

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.

as explained below. In case of the {source} keyword, the name of

the function is ignored.

If the {invoke} keyword is used, no other keywords can be used, and a

previous python command must have defined the Python function

below.  You can invoke the function as many times as you wish in your

input script.

If the {source} keyword is used, no other keywords can be used.

The argument can be a filename or a string with python commands,

either on a single line enclosed in quotes, or as multiple lines

enclosed in triple quotes. These python commands will be passed

to the python interpreter and executed immediately without registering

a python function for future execution.

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,

cases, LAMMPS has no simple way to check that something illogical is

being attempted.

The same applies to Python functions called during a simulation run at

each time step using "fix python"_fix_python.html.

:line

If you run Python code directly on your workstation, either

[Related commands:]

"shell"_shell.html, "variable"_variable.html

"shell"_shell.html, "variable"_variable.html, "fix python"_fix_python.html

[Default:] none

# 3d Lennard-Jones melt

units		lj

atom_style	atomic

lattice		fcc 0.8442

region		box block 0 10 0 10 0 10

create_box	1 box

create_atoms	1 box

mass		1 1.0

velocity	all create 3.0 87287

pair_style	lj/cut 2.5

pair_coeff	1 1 1.0 1.0 2.5

neighbor	0.3 bin

neigh_modify	every 20 delay 0 check no

python         end_of_step_callback here """

from __future__ import print_function

from lammps import lammps

def end_of_step_callback(lmp):

  L = lammps(ptr=lmp)

  t = L.extract_global("ntimestep", 0)

  print("### END OF STEP ###", t)

def post_force_callback(lmp, v):

  L = lammps(ptr=lmp)

  t = L.extract_global("ntimestep", 0)

  print("### POST_FORCE ###", t)

"""

fix		1 all nve

fix     2 all python 50 end_of_step end_of_step_callback

fix     3 all python 50 post_force post_force_callback

#dump		id all atom 50 dump.melt

#dump		2 all image 25 image.*.jpg type type &

#		axes yes 0.8 0.02 view 60 -30

#dump_modify	2 pad 3

#dump		3 all movie 25 movie.mpg type type &

#		axes yes 0.8 0.02 view 60 -30

#dump_modify	3 pad 3

thermo		50

run		250