diff --git a/doc/src/Run_formats.rst b/doc/src/Run_formats.rst new file mode 100644 index 0000000000..896ddcade2 --- /dev/null +++ b/doc/src/Run_formats.rst @@ -0,0 +1,119 @@ +File formats used by LAMMPS +=========================== + +This page provides a general overview of the kinds of files and file +formats that LAMMPS is reading and writing. + +Character Encoding +^^^^^^^^^^^^^^^^^^ + +For text files, LAMMPS uses `ASCII character encoding +`_ which represents the digits 0 to +9, the lower and upper case letters a to z, some common punctuation and +other symbols and a few whitespace characters including a regular "space +character", "line feed", "carriage return", "tabulator". These are all +represented by bytes with a value smaller than 128 and only 95 of those +128 values represent printable characters. This is sufficient to represent +most English text, but misses accented characters or umlauts or Greek +symbols and more. + +Modern text often uses `UTF-8 character encoding +`_ instead. This is a way to +represent many more different characters as defined by the Unicode +standard. This is compatible with ASCII, since the first 128 values are +identical with the ASCIII encoding. It is important to note, however, +that there are Unicode characters that look similar or even identical to +ASCII characters, but have a different representation. As a general +rule, these characters are not be correctly recognized by LAMMPS. For +some parts of LAMMPS' text processing, there are translation tables with +known "lookalike" characters that will transparently substitute them +with their ASCII equivalents. Non-ASCII lookalike characters are often +used by web browsers or PDF viewers to improve the readability of +text. Thus, when using copy-n-paste to transfer text from such an +application to your input file, you may unintentionally create text that +is not fully in ASCII encoding and may cause errors when LAMMPS is +trying to read it. + +Lines with non-printable and non-ASCII characters in text files can be +detected for example with: + +.. code-block:: bash + + env LC_ALL=C grep -n '[^ -~]' some_file.txt + +Number Formatting +^^^^^^^^^^^^^^^^^ + +Different countries and languages have different conventions to format +numbers. While in some regions commas are used for fractions and points +to indicate thousand, million and so on, this is reversed in other +regions. Modern operating systems have facilities to adjust input and +output accordingly. The exact rules are often applied according to the +value of the ``$LANG`` environment variable (e.g. "en_US.utf8"). + +For the sake of simplicity of the implementation and transferability of +results, LAMMPS does not support this and instead expects numbers being +formatted in the generic or "C" locale. The "C" locale has no +punctuation for thousand, million and so on and uses a decimal point for +fractions. One thousand would be represented as "1000.0" and not as +"1,000.0" nor as "1.000,0". + +LAMMPS also only accepts integer numbers when an integer is required, +so using "1.0" is not accepted; you have to use "1" instead. + +For floating point numbers in scientific notation, the Fortran double +precision notation "1.1d3" is not accepted either; you have to use +"1100", "1100.0" or "1.1e3". + +Input file +^^^^^^^^^^ + +A LAMMPS input file is a text file with commands. It is read +line-by-line and each line is processed *immediately*. Before looking +for commands and executing them, there is a pre-processing step where +`${variable}` and `$(expression)` constructs are expanded or evaluated +and lines that end in the ampersand character '&' are combined with the +next line (similar to Fortran 90 free format source code). + +The LAMMPS input syntax has minimal support for conditionals and loops, +but if more complex operations are required, it is recommended to use +the library interface, e.g. :doc:`from Python using the LAMMPS Python +module `. + +There is a frequent misconception about the :doc:`if command `: +this is a command for conditional execution **outside** a run or +minimization. To trigger actions on specific conditions **during** +a run is a non-trivial operation that usually requires adopting one +of the available fix commands or creating a new one. + +LAMMPS commands can change the internal state and thus the order of +commands matters and reordering them can produce different results. + +Each line must have an "end-of-line" character (line feed or carriage +return plus line feed). Some text editors do not automatically insert +one which may have the result that LAMMPS ignores the last command. +It is thus recommended, to always have an empty line at the end of an +input file. + +The specific details describing how LAMMPS input is processed and parsed +are explained in :doc:`Commands_parse`. + +Data file +^^^^^^^^^ + + +Molecule file +^^^^^^^^^^^^^ + + +Potential file +^^^^^^^^^^^^^^ + + +Restart file +^^^^^^^^^^^^ + + +Dump file +^^^^^^^^^ + diff --git a/doc/src/Run_head.rst b/doc/src/Run_head.rst index 5da5942d9b..6739df5cbb 100644 --- a/doc/src/Run_head.rst +++ b/doc/src/Run_head.rst @@ -1,10 +1,11 @@ Run LAMMPS ********** -These pages explain how to run LAMMPS once you have :doc:`installed an executable ` or :doc:`downloaded the source code ` -and :doc:`built an executable `. The :doc:`Commands ` -doc page describes how input scripts are structured and the commands -they can contain. +These pages explain how to run LAMMPS once you have :doc:`installed an +executable ` or :doc:`downloaded the source code ` and +:doc:`built an executable `. The :doc:`Commands ` doc +page describes how input scripts are structured and the commands they +can contain. .. toctree:: :maxdepth: 1 @@ -12,4 +13,5 @@ they can contain. Run_basics Run_options Run_output + Run_formats Run_windows diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 70d6b4e323..694e4ec871 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -3930,6 +3930,7 @@ username usleep usolve usr +utf util utils utsa