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

docs: completed review of build section

Browse Source
This commit is contained in:
Richard Berger
2024-08-14 15:25:49 -06:00
parent 26f9a84c4f
commit 817f92d1fe
3 changed files with 81 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
doc/src/Build_development.rst
View File

@ -181,24 +181,24 @@ The output of this command will be looking something like this:
$ ctest
Test project /home/akohlmey/compile/lammps/build-testing
Start 1: RunLammps
1/563 Test #1: RunLammps .......................................... Passed 0.28 sec
1/563 Test #1: RunLammps .................................. Passed 0.28 sec
Start 2: HelpMessage
2/563 Test #2: HelpMessage ........................................ Passed 0.06 sec
2/563 Test #2: HelpMessage ................................ Passed 0.06 sec
Start 3: InvalidFlag
3/563 Test #3: InvalidFlag ........................................ Passed 0.06 sec
3/563 Test #3: InvalidFlag ................................ Passed 0.06 sec
Start 4: Tokenizer
4/563 Test #4: Tokenizer .......................................... Passed 0.05 sec
4/563 Test #4: Tokenizer .................................. Passed 0.05 sec
Start 5: MemPool
5/563 Test #5: MemPool ............................................ Passed 0.05 sec
5/563 Test #5: MemPool .................................... Passed 0.05 sec
Start 6: ArgUtils
6/563 Test #6: ArgUtils ........................................... Passed 0.05 sec
6/563 Test #6: ArgUtils ................................... Passed 0.05 sec
[...]
Start 561: ImproperStyle:zero
561/563 Test #561: ImproperStyle:zero ................................. Passed 0.07 sec
561/563 Test #561: ImproperStyle:zero ......................... Passed 0.07 sec
Start 562: TestMliapPyUnified
562/563 Test #562: TestMliapPyUnified ................................. Passed 0.16 sec
562/563 Test #562: TestMliapPyUnified ......................... Passed 0.16 sec
Start 563: TestPairList
563/563 Test #563: TestPairList ....................................... Passed 0.06 sec
563/563 Test #563: TestPairList ............................... Passed 0.06 sec
100% tests passed, 0 tests failed out of 563
@ -216,21 +216,21 @@ The ``ctest`` command has many options, the most important ones are:
* - Option
- Function
* - -V
* - ``-V``
- verbose output: display output of individual test runs
* - -j <num>
* - ``-j <num>``
- parallel run: run <num> tests in parallel
* - -R <regex>
* - ``-R <regex>``
- run subset of tests matching the regular expression <regex>
* - -E <regex>
* - ``-E <regex>``
- exclude subset of tests matching the regular expression <regex>
* - -L <regex>
* - ``-L <regex>``
- run subset of tests with a label matching the regular expression <regex>
* - -LE <regex>
* - ``-LE <regex>``
- exclude subset of tests with a label matching the regular expression <regex>
* - -N
* - ``-N``
- dry-run: display list of tests without running them
* - -T memcheck
* - ``-T memcheck``
- run tests with valgrind memory checker (if available)
In its full implementation, the unit test framework will consist of multiple
@ -339,13 +339,13 @@ The force style test programs have a common set of options:
* - Option
- Function
* - -g <newfile>
* - ``-g <newfile>``
- regenerate reference data in new YAML file
* - -u
* - ``-u``
- update reference data in the original YAML file
* - -s
* - ``-s``
- print error statistics for each group of comparisons
* - -v
* - ``-v``
- verbose output: also print the executed LAMMPS commands
The ``ctest`` tool has no mechanism to directly pass flags to the individual
@ -359,10 +359,10 @@ set in an environment variable ``TEST_ARGS``. Example:
To add a test for a style that is not yet covered, it is usually best
to copy a YAML file for a similar style to a new file, edit the details
of the style (how to call it, how to set its coefficients) and then
run test command with either the *-g* and the replace the initial
test file with the regenerated one or the *-u* option. The *-u* option
run test command with either the ``-g`` and the replace the initial
test file with the regenerated one or the ``-u`` option. The ``-u`` option
will destroy the original file, if the generation run does not complete,
so using *-g* is recommended unless the YAML file is fully tested
so using ``-g`` is recommended unless the YAML file is fully tested
and working.
Some of the force style tests are rather slow to run and some are very
@ -512,27 +512,51 @@ After post-processing with ``gen_coverage_html`` the results are in
a folder ``coverage_html`` and can be viewed with a web browser.
The images below illustrate how the data is presented.
.. list-table::
.. only:: not latex
* - .. figure:: JPG/coverage-overview-top.png
:scale: 25%
.. list-table::
Top of the overview page
* - .. figure:: JPG/coverage-overview-top.png
:scale: 25%
- .. figure:: JPG/coverage-overview-manybody.png
:scale: 25%
Top of the overview page
Styles with good coverage
- .. figure:: JPG/coverage-overview-manybody.png
:scale: 25%
- .. figure:: JPG/coverage-file-top.png
:scale: 25%
Styles with good coverage
Top of individual source page
- .. figure:: JPG/coverage-file-top.png
:scale: 25%
- .. figure:: JPG/coverage-file-branches.png
:scale: 25%
Top of individual source page
Source page with branches
- .. figure:: JPG/coverage-file-branches.png
:scale: 25%
Source page with branches
.. only:: latex
.. figure:: JPG/coverage-overview-top.png
:width: 60%
Top of the overview page
.. figure:: JPG/coverage-overview-manybody.png
:width: 60%
Styles with good coverage
.. figure:: JPG/coverage-file-top.png
:width: 60%
Top of individual source page
.. figure:: JPG/coverage-file-branches.png
:width: 60%
Source page with branches
Coding style utilities
----------------------

29
doc/src/Build_extras.rst
View File

@ -264,10 +264,17 @@ script with the specified args:
.. code-block:: bash
make lib-gpu # print help message
make lib-gpu args="-b" # build GPU library with default Makefile.linux
make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single, altered for single-precision
make lib-gpu args="-m mpi -a sm_60 -p mixed -b" # build GPU library with mixed precision and P100 using other settings in Makefile.mpi
# print help message
make lib-gpu
# build GPU library with default Makefile.linux
make lib-gpu args="-b"
# create new Makefile.xk7.single, altered for single-precision
make lib-gpu args="-m xk7 -p single -o xk7.single"
# build GPU library with mixed precision and P100 using other settings in Makefile.mpi
make lib-gpu args="-m mpi -a sm_60 -p mixed -b"
Note that this procedure starts with a Makefile.machine in lib/gpu, as
specified by the ``-m`` switch. For your convenience, machine makefiles
@ -391,7 +398,7 @@ minutes to hours) to build. Of course you only need to do that once.)
make lib-kim
# (re-)install KIM API lib with only example models
make lib-kim args="-b "
make lib-kim args="-b"
# ditto plus one model
make lib-kim args="-b -a Glue_Ercolessi_Adams_Al__MO_324507536345_001"
@ -408,7 +415,7 @@ minutes to hours) to build. Of course you only need to do that once.)
# ditto but add one model or driver
make lib-kim args="-p <prefix> -a EAM_Dynamo_Ackland_W__MO_141627196590_002"
When using the ``-b `` option, the KIM library is built using its native
When using the ``-b`` option, the KIM library is built using its native
cmake build system. The ``lib/kim/Install.py`` script supports a
``CMAKE`` environment variable if the cmake executable is named other
than ``cmake`` on your system. Additional environment variables may be
@ -420,7 +427,7 @@ minutes to hours) to build. Of course you only need to do that once.)
# (re-)install KIM API lib using cmake3 and gnu v11 compilers
# with only example models
CMAKE=cmake3 CXX=g++-11 CC=gcc-11 FC=gfortran-11 make lib-kim args="-b "
CMAKE=cmake3 CXX=g++-11 CC=gcc-11 FC=gfortran-11 make lib-kim args="-b"
Settings for debugging OpenKIM web queries discussed below need to
be applied by adding them to the ``LMP_INC`` variable through
@ -476,9 +483,11 @@ Enabling the extra unit tests have some requirements,
Conda. More detailed information is available at:
`kim-property installation <https://github.com/openkim/kim-property#installing-kim-property>`_.
* It is also necessary to install the following KIM models:
- ``EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000``
- ``EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005``
- ``LennardJones612_UniversalShifted__MO_959249795837_003``
* ``EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000``
* ``EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005``
* ``LennardJones612_UniversalShifted__MO_959249795837_003``
See `Obtaining KIM Models <https://openkim.org/doc/usage/obtaining-models>`_
to learn how to install a pre-built binary of the OpenKIM Repository of
Models or see

2
doc/src/Build_settings.rst
View File

@ -247,7 +247,7 @@ produce the additional libraries ``libfftw3f.a`` and/or ``libfftw3f.so``\ .
Performing 3d FFTs requires communication to transpose the 3d FFT
grid. The data packing/unpacking for this can be done in one of 3
modes (ARRAY, POINTER, MEMCPY) as set by the FFT_PACK syntax above.
modes (ARRAY, POINTER, MEMCPY) as set by the ``FFT_PACK`` syntax above.
Depending on the machine, the size of the FFT grid, the number of
processors used, one option may be slightly faster. The default is
ARRAY mode.