From dd7a3a3a54e15cdf33271b75bd79837eb73d53be Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 15 Oct 2020 20:29:24 -0400 Subject: [PATCH] move the entries about using the Python module into its own (sub) toctree --- doc/src/Python_ext.rst | 9 ++- doc/src/Python_head.rst | 8 --- doc/src/Python_launch.rst | 108 ++++++++++++++++++++++++++++++++++ doc/src/Python_run.rst | 121 ++++++-------------------------------- 4 files changed, 131 insertions(+), 115 deletions(-) create mode 100644 doc/src/Python_launch.rst diff --git a/doc/src/Python_ext.rst b/doc/src/Python_ext.rst index 40f6e10609..02e57f559e 100644 --- a/doc/src/Python_ext.rst +++ b/doc/src/Python_ext.rst @@ -1,16 +1,19 @@ Extending the library and Python interface ****************************************** -As noted above, these Python class methods correspond one-to-one with +As noted previously, the Python class methods correspond one-to-one with the functions in the LAMMPS library interface in ``src/library.cpp`` and -``library.h``. This means you can extend the Python wrapper via the -following steps: +``library.h``. This means you can extend the Python wrapper by +following these steps: * Add a new interface function to ``src/library.cpp`` and ``src/library.h``. * Rebuild LAMMPS as a shared library. * Add a wrapper method to ``python/lammps.py`` for this interface function. +* Define the corresponding ``argtypes`` list and ``restype`` + in the ``lammps.__init__()`` function. +* Re-install the shared library and the python module, if needed * You should now be able to invoke the new interface function from a Python script. diff --git a/doc/src/Python_head.rst b/doc/src/Python_head.rst index bb18dd02cd..09071171ad 100644 --- a/doc/src/Python_head.rst +++ b/doc/src/Python_head.rst @@ -10,14 +10,6 @@ together. Python_overview Python_install Python_run - Python_create - Python_execute - Python_properties - Python_atoms - Python_objects - Python_scatter - Python_neighbor - Python_config Python_module Python_ext Python_call diff --git a/doc/src/Python_launch.rst b/doc/src/Python_launch.rst new file mode 100644 index 0000000000..02963c945e --- /dev/null +++ b/doc/src/Python_launch.rst @@ -0,0 +1,108 @@ +Running LAMMPS and Python in serial +----------------------------------- + +To run a LAMMPS in serial, type these lines into Python +interactively from the ``bench`` directory: + +.. code-block:: python + + >>> from lammps import lammps + >>> lmp = lammps() + >>> lmp.file("in.lj") + +Or put the same lines in the file ``test.py`` and run it as + +.. code-block:: bash + + $ python3 test.py + +Either way, you should see the results of running the ``in.lj`` benchmark +on a single processor appear on the screen, the same as if you had +typed something like: + +.. code-block:: bash + + lmp_serial -in in.lj + +Running LAMMPS and Python in parallel with MPI +---------------------------------------------- + +To run LAMMPS in parallel, assuming you have installed the +`mpi4py `_ package as discussed +:ref:`python_install_mpi4py`, create a ``test.py`` file containing these lines: + +.. code-block:: python + + from mpi4py import MPI + from lammps import lammps + lmp = lammps() + lmp.file("in.lj") + me = MPI.COMM_WORLD.Get_rank() + nprocs = MPI.COMM_WORLD.Get_size() + print("Proc %d out of %d procs has" % (me,nprocs),lmp) + MPI.Finalize() + +You can run the script in parallel as: + +.. code-block:: bash + + $ mpirun -np 4 python3 test.py + +and you should see the same output as if you had typed + +.. code-block:: bash + + $ mpirun -np 4 lmp_mpi -in in.lj + +Note that without the mpi4py specific lines from ``test.py`` + +.. code-block:: + + from lammps import lammps + lmp = lammps() + lmp.file("in.lj") + +running the script with ``mpirun`` on :math:`P` processors would lead to +:math:`P` independent simulations to run parallel, each with a single +processor. Therefore, if you use the mpi4py lines and you see multiple LAMMPS +single processor outputs, mpi4py is not working correctly. + +Also note that once you import the mpi4py module, mpi4py initializes MPI +for you, and you can use MPI calls directly in your Python script, as +described in the mpi4py documentation. The last line of your Python +script should be ``MPI.finalize()``, to insure MPI is shut down +correctly. + + +Running Python scripts +---------------------- + +Note that any Python script (not just for LAMMPS) can be invoked in +one of several ways: + +.. code-block:: bash + + $ python script.py + $ python -i script.py + $ ./script.py + +The last command requires that the first line of the script be +something like this: + +.. code-block:: bash + + #!/usr/bin/python + #!/usr/bin/python -i + +where the path points to where you have Python installed, and that you +have made the script file executable: + +.. code-block:: bash + + $ chmod +x script.py + +Without the ``-i`` flag, Python will exit when the script finishes. +With the ``-i`` flag, you will be left in the Python interpreter when +the script finishes, so you can type subsequent commands. As +mentioned above, you can only run Python interactively when running +Python on a single processor, not in parallel. diff --git a/doc/src/Python_run.rst b/doc/src/Python_run.rst index 077945d8a9..3e0d52f7ac 100644 --- a/doc/src/Python_run.rst +++ b/doc/src/Python_run.rst @@ -1,110 +1,23 @@ Run LAMMPS from Python ====================== -Running LAMMPS and Python in serial: -------------------------------------- +After compiling the LAMMPS shared library and making it ready to use, +you can now write and run Python scripts that import the LAMMPS Python +module and launch LAMMPS simulations through Python scripts. +The following pages take you through the various steps necessary, +what functionality is available and give some examples how to use it. -To run a LAMMPS in serial, type these lines into Python -interactively from the ``bench`` directory: +------ -.. code-block:: python +.. toctree:: + :maxdepth: 1 - >>> from lammps import lammps - >>> lmp = lammps() - >>> lmp.file("in.lj") - -Or put the same lines in the file ``test.py`` and run it as - -.. code-block:: bash - - $ python3 test.py - -Either way, you should see the results of running the ``in.lj`` benchmark -on a single processor appear on the screen, the same as if you had -typed something like: - -.. code-block:: bash - - lmp_serial -in in.lj - -Running LAMMPS and Python in parallel with MPI ----------------------------------------------- - -To run LAMMPS in parallel, assuming you have installed the -`mpi4py `_ package as discussed -:ref:`python_install_mpi4py`, create a ``test.py`` file containing these lines: - -.. code-block:: python - - from mpi4py import MPI - from lammps import lammps - lmp = lammps() - lmp.file("in.lj") - me = MPI.COMM_WORLD.Get_rank() - nprocs = MPI.COMM_WORLD.Get_size() - print("Proc %d out of %d procs has" % (me,nprocs),lmp) - MPI.Finalize() - -You can run the script in parallel as: - -.. code-block:: bash - - $ mpirun -np 4 python3 test.py - -and you should see the same output as if you had typed - -.. code-block:: bash - - $ mpirun -np 4 lmp_mpi -in in.lj - -Note that without the mpi4py specific lines from ``test.py`` - -.. code-block:: - - from lammps import lammps - lmp = lammps() - lmp.file("in.lj") - -running the script with ``mpirun`` on :math:`P` processors would lead to -:math:`P` independent simulations to run parallel, each with a single -processor. Therefore, if you use the mpi4py lines and you see multiple LAMMPS -single processor outputs, mpi4py is not working correctly. - -Also note that once you import the mpi4py module, mpi4py initializes MPI -for you, and you can use MPI calls directly in your Python script, as -described in the mpi4py documentation. The last line of your Python -script should be ``MPI.finalize()``, to insure MPI is shut down -correctly. - -Running Python scripts ----------------------- - -Note that any Python script (not just for LAMMPS) can be invoked in -one of several ways: - -.. code-block:: bash - - $ python script.py - $ python -i script.py - $ ./script.py - -The last command requires that the first line of the script be -something like this: - -.. code-block:: bash - - #!/usr/bin/python - #!/usr/bin/python -i - -where the path points to where you have Python installed, and that you -have made the script file executable: - -.. code-block:: bash - - $ chmod +x script.py - -Without the ``-i`` flag, Python will exit when the script finishes. -With the ``-i`` flag, you will be left in the Python interpreter when -the script finishes, so you can type subsequent commands. As -mentioned above, you can only run Python interactively when running -Python on a single processor, not in parallel. + Python_launch + Python_create + Python_execute + Python_properties + Python_atoms + Python_objects + Python_scatter + Python_neighbor + Python_config