ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update documentation for removal of MPIIO package

Browse Source
This commit is contained in:
Axel Kohlmeyer
2023-08-20 22:14:01 -04:00
parent 4de7694bbe
commit d230ae49c4
13 changed files with 70 additions and 204 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
doc/src/Build_basics.rst
View File

@ -90,7 +90,7 @@ standard. A more detailed discussion of that is below.
directory, or ``make`` from the ``src/STUBS`` dir. If the build
fails, you may need to edit the ``STUBS/Makefile`` for your
platform. The stubs library does not provide MPI/IO functions
required by some LAMMPS packages, e.g. ``MPIIO`` or ``LATBOLTZ``,
required by some LAMMPS packages, e.g. ``LATBOLTZ``,
and thus is not compatible with those packages.
.. note::
@ -128,14 +128,13 @@ and adds vectorization support when compiled with compatible compilers,
in particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS``
package can be compiled to include OpenMP threading.
In addition, there are a few commands in LAMMPS that have native
OpenMP support included as well. These are commands in the ``MPIIO``,
``ML-SNAP``, ``DIFFRACTION``, and ``DPD-REACT`` packages.
Furthermore, some packages support OpenMP threading indirectly through
the libraries they interface to: e.g. ``KSPACE``, and ``COLVARS``.
See the :doc:`Packages details <Packages_details>` page for more info
on these packages, and the pages for their respective commands for
OpenMP threading info.
In addition, there are a few commands in LAMMPS that have native OpenMP
support included as well. These are commands in the ``ML-SNAP``,
``DIFFRACTION``, and ``DPD-REACT`` packages. Furthermore, some packages
support OpenMP threading indirectly through the libraries they interface
to: e.g. ``KSPACE``, and ``COLVARS``. See the :doc:`Packages details
<Packages_details>` page for more info on these packages, and the pages
for their respective commands for OpenMP threading info.
For CMake, if you use ``BUILD_OMP=yes``, you can use these packages
and turn on their native OpenMP support and turn on their native OpenMP

4
doc/src/Commands_dump.rst
View File

@ -23,17 +23,14 @@ An alphabetic list of all LAMMPS :doc:`dump <dump>` commands.
* :doc:`atom <dump>`
* :doc:`atom/adios <dump_adios>`
* :doc:`atom/gz <dump>`
* :doc:`atom/mpiio <dump>`
* :doc:`atom/zstd <dump>`
* :doc:`cfg <dump>`
* :doc:`cfg/gz <dump>`
* :doc:`cfg/mpiio <dump>`
* :doc:`cfg/uef <dump_cfg_uef>`
* :doc:`cfg/zstd <dump>`
* :doc:`custom <dump>`
* :doc:`custom/adios <dump_adios>`
* :doc:`custom/gz <dump>`
* :doc:`custom/mpiio <dump>`
* :doc:`custom/zstd <dump>`
* :doc:`dcd <dump>`
* :doc:`grid <dump>`
@ -51,7 +48,6 @@ An alphabetic list of all LAMMPS :doc:`dump <dump>` commands.
* :doc:`xtc <dump>`
* :doc:`xyz <dump>`
* :doc:`xyz/gz <dump>`
* :doc:`xyz/mpiio <dump>`
* :doc:`xyz/zstd <dump>`
* :doc:`yaml <dump>`

19
doc/src/Commands_removed.rst
View File

@ -85,6 +85,25 @@ The same functionality is available through
:doc:`bond style mesocnt <bond_mesocnt>` and
:doc:`angle style mesocnt <angle_mesocnt>`.
MPIIO package
-------------
.. deprecated:: TBD
The MPIIO package has been removed from LAMMPS since it was unmaintained
for many years and thus not updated to incorporate required changes that
had been applied to the corresponding non-MPIIO commands. As a
consequence the MPIIO commands had become unreliable and sometimes
crashing LAMMPS or corrupting data. Similar functionality is available
through the :ref:`ADIOS package <PKG-ADIOS>` and the :ref:`NETCDF
package <PKG-NETCDF>`. Also, the :doc:`dump_modify nfile or dump_modify
fileper <dump_modify>` keywords may be used for an efficient way of
writing out dump files when running on large numbers of processors.
Similarly, the "nfile" and "fileper" keywords exist for restarts:
see :doc:`restart <restart>`, :doc:`read_restart <read_restart>`,
:doc:`write_restart <write_restart>`.
MSCG package
------------

6
doc/src/Errors_messages.rst
View File

@ -7148,9 +7148,6 @@ keyword to allow for additional bonds to be formed
*Read_dump xyz fields do not have consistent scaling/wrapping*
Self-explanatory.
*Reading from MPI-IO filename when MPIIO package is not installed*
Self-explanatory.
*Reax_defs.h setting for NATDEF is too small*
Edit the setting in the ReaxFF library and re-compile the
library and re-build LAMMPS.
@ -8489,9 +8486,6 @@ keyword to allow for additional bonds to be formed
The write_restart command cannot be used before a read_data,
read_restart, or create_box command.
*Writing to MPI-IO filename when MPIIO package is not installed*
Self-explanatory.
*Zero length rotation vector with displace_atoms*
Self-explanatory.

2
doc/src/Install_mac.rst
View File

@ -5,7 +5,7 @@ LAMMPS can be downloaded, built, and configured for macOS with `Homebrew
<homebrew_>`_. (Alternatively, see the installation instructions for
:doc:`downloading an executable via Conda <Install_conda>`.) The
following LAMMPS packages are unavailable at this time because of
additional requirements not yet met: GPU, KOKKOS, MSCG, MPIIO, POEMS,
additional requirements not yet met: GPU, KOKKOS, MSCG, POEMS,
VORONOI.
After installing Homebrew, you can install LAMMPS on your system with

9
doc/src/Install_windows.rst
View File

@ -18,11 +18,10 @@ needed to run in parallel with MPI.
The LAMMPS binaries contain *all* :doc:`optional packages <Packages>`
included in the source distribution except: ADIOS, H5MD, KIM, ML-PACE,
ML-QUIP, MSCG, NETCDF, PLUMED, QMMM, SCAFACOS, and VTK. The serial
version also does not include the MPIIO and LATBOLTZ packages. The
PYTHON package is only available in the Python installers that bundle a
Python runtime. The GPU package is compiled for OpenCL with mixed
precision kernels.
ML-QUIP, MSCG, NETCDF, QMMM, SCAFACOS, and VTK. The serial version also
does not include the LATBOLTZ package. The PYTHON package is only
available in the Python installers that bundle a Python runtime. The
GPU package is compiled for OpenCL with mixed precision kernels.
The LAMMPS library is compiled as a shared library and the
:doc:`LAMMPS Python module <Python_module>` is installed, so that

33
doc/src/Packages_details.rst
View File

@ -87,7 +87,6 @@ page gives those details.
* :ref:`MOFFF <PKG-MOFFF>`
* :ref:`MOLECULE <PKG-MOLECULE>`
* :ref:`MOLFILE <PKG-MOLFILE>`
* :ref:`MPIIO <PKG-MPIIO>`
* :ref:`NETCDF <PKG-NETCDF>`
* :ref:`OPENMP <PKG-OPENMP>`
* :ref:`OPT <PKG-OPT>`
@ -2033,38 +2032,6 @@ This package has :ref:`specific installation instructions <molfile>` on the :doc
----------
.. _PKG-MPIIO:
MPIIO package
-------------
**Contents:**
Support for parallel output/input of dump and restart files via the
MPIIO library. It adds :doc:`dump styles <dump>` with a "mpiio" in
their style name. Restart files with an ".mpiio" suffix are also
written and read in parallel.
.. warning::
The MPIIO package is currently unmaintained and has become
unreliable. Use with caution.
**Install:**
The MPIIO package requires that LAMMPS is build in :ref:`MPI parallel mode <serial>`.
**Supporting info:**
* src/MPIIO: filenames -> commands
* :doc:`dump <dump>`
* :doc:`restart <restart>`
* :doc:`write_restart <write_restart>`
* :doc:`read_restart <read_restart>`
----------
.. _PKG-NETCDF:
NETCDF package

5
doc/src/Packages_list.rst
View File

@ -333,11 +333,6 @@ whether an extra library is needed to build and use the package:
- :doc:`dump molfile <dump_molfile>`
- n/a
- ext
* - :ref:`MPIIO <PKG-MPIIO>`
- MPI parallel I/O dump and restart
- :doc:`dump <dump>`
- n/a
- no
* - :ref:`NETCDF <PKG-NETCDF>`
- dump output via NetCDF
- :doc:`dump netcdf <dump_netcdf>`

44
doc/src/dump.rst
View File

@ -14,10 +14,6 @@
.. index:: dump custom/gz
.. index:: dump local/gz
.. index:: dump xyz/gz
.. index:: dump atom/mpiio
.. index:: dump cfg/mpiio
.. index:: dump custom/mpiio
.. index:: dump xyz/mpiio
.. index:: dump atom/zstd
.. index:: dump cfg/zstd
.. index:: dump custom/zstd
@ -63,7 +59,7 @@ Syntax
* ID = user-assigned name for the dump
* group-ID = ID of the group of atoms to be dumped
* style = *atom* or *atom/adios* or *atom/gz* or *atom/zstd* or *atom/mpiio* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/mpiio* or *cfg/uef* or *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *custom/adios* or *dcd* or *grid* or *grid/vtk* or *h5md* or *image* or *local* or *local/gz* or *local/zstd* or *molfile* or *movie* or *netcdf* or *netcdf/mpiio* or *vtk* or *xtc* or *xyz* or *xyz/gz* or *xyz/zstd* or *xyz/mpiio* or *yaml*
* style = *atom* or *atom/adios* or *atom/gz* or *atom/zstd* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/uef* or *custom* or *custom/gz* or *custom/zstd* or *custom/adios* or *dcd* or *grid* or *grid/vtk* or *h5md* or *image* or *local* or *local/gz* or *local/zstd* or *molfile* or *movie* or *netcdf* or *netcdf/mpiio* or *vtk* or *xtc* or *xyz* or *xyz/gz* or *xyz/zstd* or *yaml*
* N = dump on timesteps which are multiples of N
* file = name of file to write dump info to
* attribute1,attribute2,... = list of attributes for a particular style
@ -74,13 +70,11 @@ Syntax
*atom/adios* attributes = none, discussed on :doc:`dump atom/adios <dump_adios>` page
*atom/gz* attributes = none
*atom/zstd* attributes = none
*atom/mpiio* attributes = none
*cfg* attributes = same as *custom* attributes, see below
*cfg/gz* attributes = same as *custom* attributes, see below
*cfg/zstd* attributes = same as *custom* attributes, see below
*cfg/mpiio* attributes = same as *custom* attributes, see below
*cfg/uef* attributes = same as *custom* attributes, discussed on :doc:`dump cfg/uef <dump_cfg_uef>` page
*custom*, *custom/gz*, *custom/zstd*, *custom/mpiio* attributes = see below
*custom*, *custom/gz*, *custom/zstd* attributes = see below
*custom/adios* attributes = same as *custom* attributes, discussed on :doc:`dump custom/adios <dump_adios>` page
*dcd* attributes = none
*h5md* attributes = discussed on :doc:`dump h5md <dump_h5md>` page
@ -97,10 +91,9 @@ Syntax
*xyz* attributes = none
*xyz/gz* attributes = none
*xyz/zstd* attributes = none
*xyz/mpiio* attributes = none
*yaml* attributes = same as *custom* attributes, see below
* *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/mpiio* or *cfg/uef* or *netcdf* or *netcdf/mpiio* or *yaml* attributes:
* *custom* or *custom/gz* or *custom/zstd* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/uef* or *netcdf* or *netcdf/mpiio* or *yaml* attributes:
.. parsed-literal::
@ -179,11 +172,9 @@ Examples
.. code-block:: LAMMPS
dump myDump all atom 100 dump.lammpstrj
dump myDump all atom/mpiio 100 dump.atom.mpiio
dump myDump all atom/gz 100 dump.atom.gz
dump myDump all atom/zstd 100 dump.atom.zst
dump 2 subgroup atom 50 dump.run.bin
dump 2 subgroup atom/mpiio 50 dump.run.mpiio.bin
dump 4a all custom 100 dump.myforce.* id type x y vx fx
dump 4a all custom 100 dump.myvel.lammpsbin id type x y z vx vy vz
dump 4b flow custom 100 dump.%.myforce id type c_myF[3] v_ke
@ -622,27 +613,10 @@ when running on large numbers of processors.
Note that using the "\*" and "%" characters together can produce a
large number of small dump files!
For styles that end with *mpiio* an ".mpiio" must appear somewhere in
the specified filename. These styles write their dump file in
parallel via the MPI-IO library, which is part of the MPI standard for
versions 2.0 and above. Note these styles are identical in command
syntax to the corresponding styles without "mpiio". Likewise, the
dump files produced by these MPI-IO styles are identical in format to
the files produced by their non-MPI-IO style counterparts. This means
you can write a dump file using MPI-IO and use the :doc:`read_dump
<read_dump>` command or perform other post-processing, just as if the
dump file was not written using MPI-IO.
.. deprecated:: TBD
Because MPI-IO dump files are one large file which all processors
write to, you cannot use the "%" wildcard character described above in
the filename. However you can use the ".bin" or ".lammpsbin" suffix
described below. Again, this file will be written in parallel and
have the same binary format as if it were written without MPI-IO.
.. warning::
The MPIIO package within LAMMPS is currently unmaintained and has
become unreliable. Use with caution.
The MPIIO package and the the corresponding "/mpiio" dump styles, except
for the unrelated "netcdf/mpiio" style were removed from LAMMPS.
----------
@ -956,11 +930,6 @@ the COMPRESS package. They are only enabled if LAMMPS was built with
that package. See the :doc:`Build package <Build_package>` page for
more info.
The *atom/mpiio*, *cfg/mpiio*, *custom/mpiio*, and *xyz/mpiio* styles
are part of the MPIIO package. They are only enabled if LAMMPS was
built with that package. See the :doc:`Build package <Build_package>`
page for more info.
The *xtc*, *dcd*, and *yaml* styles are part of the EXTRA-DUMP package.
They are only enabled if LAMMPS was built with that package. See the
:doc:`Build package <Build_package>` page for more info.
@ -971,6 +940,7 @@ Related commands
:doc:`dump atom/adios <dump_adios>`, :doc:`dump custom/adios <dump_adios>`,
:doc:`dump cfg/uef <dump_cfg_uef>`, :doc:`dump h5md <dump_h5md>`,
:doc:`dump image <dump_image>`, :doc:`dump molfile <dump_molfile>`,
:doc:`dump netcdf <dump_netcdf>`, :doc:`dump netcdf/mpiio <dump_netcdf>`,
:doc:`dump_modify <dump_modify>`, :doc:`undump <undump>`,
:doc:`write_dump <write_dump>`

46
doc/src/dump_modify.rst
View File

@ -124,17 +124,6 @@ Description
Modify the parameters of a previously defined dump command. Not all
parameters are relevant to all dump styles.
As explained on the :doc:`dump <dump>` doc page, the *atom/mpiio*,
*custom/mpiio*, and *xyz/mpiio* dump styles are identical in command
syntax and in the format of the dump files they create, to the
corresponding styles without "mpiio", except the single dump file they
produce is written in parallel via the MPI-IO library. Thus if a
dump_modify option below is valid for the *atom* style, it is also
valid for the *atom/mpiio* style, and similarly for the other styles
which allow for use of MPI-IO.
----------
Unless otherwise noted, the following keywords apply to all the
various dump styles, including the :doc:`dump image <dump_image>` and
:doc:`dump movie <dump_image>` styles.
@ -181,19 +170,20 @@ extra buffering.
.. versionadded:: 4May2022
The *colname* keyword can be used to change the default header keyword
for dump styles: *atom*, *custom*, *cfg*, and *local* and their compressed,
ADIOS, and MPIIO variants. The setting for *ID string* replaces the default
text with the provided string. *ID* can be a positive integer when it
represents the column number counting from the left, a negative integer
when it represents the column number from the right (i.e. -1 is the last
column/keyword), or a custom dump keyword (or compute, fix, property, or
variable reference) and then it replaces the string for that specific
keyword. For *atom* dump styles only the keywords "id", "type", "x",
"y", "z", "ix", "iy", "iz" can be accessed via string regardless of
whether scaled or unwrapped coordinates were enabled or disabled, and
it always assumes 8 columns for indexing regardless of whether image
flags are enabled or not. For dump style *cfg* only changes to the
"auxiliary" keywords (6th or later keyword) will become visible.
for dump styles: *atom*, *custom*, *cfg*, and *local* and their
compressed, ADIOS variants. The setting for *ID string* replaces the
default text with the provided string. *ID* can be a positive integer
when it represents the column number counting from the left, a negative
integer when it represents the column number from the right (i.e. -1 is
the last column/keyword), or a custom dump keyword (or compute, fix,
property, or variable reference) and then it replaces the string for
that specific keyword. For *atom* dump styles only the keywords "id",
"type", "x", "y", "z", "ix", "iy", "iz" can be accessed via string
regardless of whether scaled or unwrapped coordinates were enabled or
disabled, and it always assumes 8 columns for indexing regardless of
whether image flags are enabled or not. For dump style *cfg* only
changes to the "auxiliary" keywords (6th or later keyword) will become
visible.
The *colname* keyword can be used multiple times. If multiple *colname*
settings refer to the same keyword, the last setting has precedence. A
@ -417,10 +407,10 @@ performed with dump style *xtc*\ .
----------
The *format* keyword can be used to change the default numeric format output
by the text-based dump styles: *atom*, *local*, *custom*, *cfg*, and
*xyz* styles, and their MPIIO variants. Only the *line* or *none*
options can be used with the *atom* and *xyz* styles.
The *format* keyword can be used to change the default numeric format
output by the text-based dump styles: *atom*, *local*, *custom*, *cfg*,
and *xyz* styles. Only the *line* or *none* options can be used with the
*atom* and *xyz* styles.
All the specified format strings are C-style formats, such as used by
the C/C++ printf() command. The *line* keyword takes a single

20
doc/src/read_restart.rst
View File

@ -19,7 +19,6 @@ Examples
read_restart save.10000
read_restart restart.*
read_restart restart.*.mpiio
Description
"""""""""""
@ -120,22 +119,6 @@ different the number of processors in the current LAMMPS simulation.
This can be a fast mode of input on parallel machines that support
parallel I/O.
A restart file can also be read in parallel as one large binary file
via the MPI-IO library, assuming it was also written with MPI-IO.
MPI-IO is part of the MPI standard for versions 2.0 and above. Using
MPI-IO requires two steps. First, build LAMMPS with its MPIIO package
installed, e.g.
.. code-block:: bash
make yes-mpiio # installs the MPIIO package
make mpi # build LAMMPS for your platform
Second, use a restart filename which contains ".mpiio". Note that it
does not have to end in ".mpiio", just contain those characters.
Unlike MPI-IO dump files, a particular restart file must be both
written and read using MPI-IO.
----------
Here is the list of information included in a restart file, which
@ -268,8 +251,7 @@ information about these bonds is written to the restart file.
Restrictions
""""""""""""
To write and read restart files in parallel with MPI-IO, the MPIIO
package must be installed.
none
Related commands
""""""""""""""""

39
doc/src/restart.rst
View File

@ -33,7 +33,6 @@ Examples
restart 0
restart 1000 poly.restart
restart 1000 poly.restart.mpiio
restart 1000 restart.*.equil
restart 10000 poly.%.1 poly.%.2 nfile 10
restart v_mystep poly.restart
@ -81,21 +80,6 @@ of output and subsequent input on parallel machines that support
parallel I/O. The optional *fileper* and *nfile* keywords discussed
below can alter the number of files written.
The restart file can also be written in parallel as one large binary
file via the MPI-IO library, which is part of the MPI standard for
versions 2.0 and above. Using MPI-IO requires two steps. First,
build LAMMPS with its MPIIO package installed, e.g.
.. code-block:: bash
make yes-mpiio # installs the MPIIO package
make mpi # build LAMMPS for your platform
Second, use a restart filename which contains ".mpiio". Note that it
does not have to end in ".mpiio", just contain those characters.
Unlike MPI-IO dump files, a particular restart file must be both
written and read using MPI-IO.
Restart files are written on timesteps that are a multiple of N but
not on the first timestep of a run or minimization. You can use the
:doc:`write_restart <write_restart>` command to write a restart file
@ -104,15 +88,17 @@ timestep of a run unless it is a multiple of N. A restart file is
written on the last timestep of a minimization if N > 0 and the
minimization converges.
Instead of a numeric value, N can be specified as an :doc:`equal-style variable <variable>`, which should be specified as v_name, where
name is the variable name. In this case, the variable is evaluated at
the beginning of a run to determine the next timestep at which a
restart file will be written out. On that timestep, the variable will
be evaluated again to determine the next timestep, etc. Thus the
variable should return timestep values. See the stagger() and
logfreq() and stride() math functions for :doc:`equal-style variables <variable>`, as examples of useful functions to use in
this context. Other similar math functions could easily be added as
options for :doc:`equal-style variables <variable>`.
Instead of a numeric value, N can be specified as an :doc:`equal-style
variable <variable>`, which should be specified as v_name, where name is
the variable name. In this case, the variable is evaluated at the
beginning of a run to determine the next timestep at which a restart
file will be written out. On that timestep, the variable will be
evaluated again to determine the next timestep, etc. Thus the variable
should return timestep values. See the stagger() and logfreq() and
stride() math functions for :doc:`equal-style variables <variable>`, as
examples of useful functions to use in this context. Other similar math
functions could easily be added as options for :doc:`equal-style
variables <variable>`.
For example, the following commands will write restart files
every step from 1100 to 1200, and could be useful for debugging
@ -170,8 +156,7 @@ next 3 processors and write it to a restart file.
Restrictions
""""""""""""
To write and read restart files in parallel with MPI-IO, the MPIIO
package must be installed.
none
Related commands
""""""""""""""""

30
doc/src/write_restart.rst
View File

@ -27,7 +27,6 @@ Examples
.. code-block:: LAMMPS
write_restart restart.equil
write_restart restart.equil.mpiio
write_restart poly.%.* nfile 10
Description
@ -53,32 +52,6 @@ output and subsequent input on parallel machines that support parallel
I/O. The optional *fileper* and *nfile* keywords discussed below can
alter the number of files written.
The restart file can also be written in parallel as one large binary
file via the MPI-IO library, which is part of the MPI standard for
versions 2.0 and above. Using MPI-IO requires two steps. First,
build LAMMPS with its MPIIO package installed, e.g.
.. tabs::
.. tab:: CMake build
.. code-block:: bash
cmake . -DPKG_MPIIO=on # enables the MPIIO package in the build folder
cmake --build . # recompiles LAMMPS with the package code included
.. tab:: Traditional make
.. code-block:: bash
make yes-mpiio # installs the MPIIO package
make mpi # build LAMMPS for your platform
Second, use a restart filename which contains ".mpiio". Note that it
does not have to end in ".mpiio", just contain those characters.
Unlike MPI-IO dump files, a particular restart file must be both
written and read using MPI-IO.
Restart files can be read by a :doc:`read_restart <read_restart>`
command to restart a simulation from a particular state. Because the
file is binary (to enable exact restarts), it may not be readable on
@ -128,9 +101,6 @@ before the restart file is written. This means that your system must
be ready to perform a simulation before using this command (force
fields setup, atom masses initialized, etc).
To write and read restart files in parallel with MPI-IO, the MPIIO
package must be installed.
Related commands
""""""""""""""""