Merge pull request lammps#4502 from akohlmey/collected-small-fixes

Collected small changes and fixes

Author: akohlmey

.github/release_steps.md

@@ -216,7 +216,7 @@ and using the CMake settings:
 
 ``` sh
 -D CMAKE_OSX_ARCHITECTURES=arm64;x86_64
--D CMAKE_OSX_DEPLOYMENT_TARGER=11.0
+-D CMAKE_OSX_DEPLOYMENT_TARGET=11.0
 ```
 
 This will add the compiler flags `-arch arm64 -arch x86_64
@@ -324,6 +324,47 @@ At this point it should be possible to do a fast-forward merge of
 
 ### Push branches and tags
 
+## LAMMPS Stable Update Release
 
+After making a stable release, bugfixes from the 'develop' branch
+are selectively backported to the 'maintenance' branch.  This is
+done with "git cherry-pick \<commit hash\>' wherever possible.
+The LAMMPS\_UPDATE define in "src/version.h" is set to "Maintenance".
 
-## LAMMPS Stable Update Release
+### Prerequesites
+
+When a sufficient number of bugfixes has accumulated or an urgent
+or important bugfix needs to be distributed a new stable update
+release is made.  To make this publicly visible a pull request
+is submitted that will merge 'maintenance' into 'stable'.  Before
+merging, set LAMMPS\_UPDATE in "src/version.h" to "Update #" with
+"#" indicating the update count (1, 2, and so on).
+Also draft suitable release notes under https://github.com/lammps/lammps/releases
+
+### Fast-forward merge of 'maintenance' into 'stable', apply tag, and publish
+
+Do a fast-forward merge of 'maintenance' to 'stable' and then
+apply the stable\_DMmmYYYY\_update# tag and push branch and tag
+to GitHub. The corresponding pull request will be automatically
+closed.   Example:
+
+```
+git checkout maintenance
+git pull
+git checkout stable
+git pull
+git merge --ff-only maintenance
+git tag -s -m 'Update 2 for Stable LAMMPS version 29 August 2024' stable_29Aug2024_update2
+git push [email protected]:lammps/lammps.git --tags maintenance stable
+```
+
+Associate draft release notes with new tag and publish as "latest release".
+
+On https://ci.lammps.org/ go to "dev", "stable" and manually execute
+the "update\_release" task. This will update https://docs.lammps.org/stable
+and prepare a stable tarball.
+
+### Build and upload binary packages and source tarball to GitHub
+
+The build procedure is the same as for the feature releases, only
+that packages are built from the 'stable' branch.

doc/src/Build_cmake.rst

@@ -119,6 +119,13 @@ configured) and additional files like LAMMPS API headers, manpages,
 potential and force field files.  The location of the installation tree
 defaults to ``${HOME}/.local``.
 
+.. note::
+
+   If you have set `-D CMAKE_INSTALL_PREFIX` to install LAMMPS into a
+   system location on a Linux machine , you may also have to run (as
+   root) the `ldconfig` program to update the cache file for fast lookup
+   of system shared libraries.
+
 .. _cmake_options:
 
 Configuration and build options

doc/src/Build_manual.rst

@@ -221,9 +221,10 @@ HTML as a quick-n-dirty way of checking your manual page.
 
 This translation uses `Pandoc <https://pandoc.org>`_ instead of Sphinx
 and thus all special Sphinx features (cross-references, advanced tables,
-embedding of Python docstring and doxygen documentation, and so on) will
-not render correctly.  But this is a **very fast** way to check the content
-as HTML while writing the documentation.
+embedding of Python docstrings or doxygen documentation, and so on) will
+not render correctly.  Most embedded math should render correctly.  This
+is a **very fast** way to check the syntax and layout of a documentation
+file translated to HTML while writing it.
 
 To translate **all** manual pages, you can type ``make fasthtml`` at the
 command line.  The translated HTML files are then in the ``fasthtml``

doc/src/Build_settings.rst

@@ -13,7 +13,8 @@ explains how to do this for building both with CMake and make.
 * `Size of LAMMPS integer types and size limits`_
 * `Read or write compressed files`_
 * `Output of JPEG, PNG, and movie files`_ via the :doc:`dump image <dump_image>` or :doc:`dump movie <dump_image>` commands
-* `Support for downloading files`_
+* `Support for downloading files from the input`_
+* `Prevent download of large potential files`_
 * `Memory allocation alignment`_
 * `Workaround for long long integers`_
 * `Exception handling when using LAMMPS as a library`_ to capture errors
@@ -509,8 +510,8 @@ during a run.
 
 .. _libcurl:
 
-Support for downloading files
------------------------------
+Support for downloading files from the input
+--------------------------------------------
 
 .. versionadded:: 29Aug2024
 
@@ -553,6 +554,25 @@ LAMMPS is compiled accordingly which needs the following settings:
 
 ----------
 
+.. _download_pot:
+
+Prevent download of large potential files
+-----------------------------------------
+
+.. versionadded:: 8Feb2023
+
+LAMMPS bundles a selection of potential files in the ``potentials``
+folder as examples of how those kinds of potential files look like and
+for use with the provided input examples in the ``examples`` tree.  To
+keep the size of the distributed LAMMPS source package small, very large
+potential files (> 5 MBytes) are not bundled, but only downloaded on
+demand when the :doc:`corresponding package <Packages_list>` is
+installed.  This automatic download can be prevented when :doc:`building
+LAMMPS with CMake <Build_cmake>` by adding the setting `-D
+DOWNLOAD_POTENTIALS=off` when configuring.
+
+----------
+
 .. _align:
 
 Memory allocation alignment

doc/src/Howto_python.rst

@@ -62,17 +62,17 @@ with :ref:`PNG, JPEG and FFMPEG output support <graphics>` enabled.
 
          cd $LAMMPS_DIR/src
 
-         # add packages if necessary
+         # add LAMMPS packages if necessary
          make yes-MOLECULE
          make yes-PYTHON
 
          # compile shared library using Makefile
          make mpi mode=shlib LMP_INC="-DLAMMPS_PNG -DLAMMPS_JPEG -DLAMMPS_FFMPEG" JPG_LIB="-lpng -ljpeg"
 
-Step 2: Installing the LAMMPS Python package
-""""""""""""""""""""""""""""""""""""""""""""
+Step 2: Installing the LAMMPS Python module
+"""""""""""""""""""""""""""""""""""""""""""
 
-Next install the LAMMPS Python package into your current Python installation with:
+Next install the LAMMPS Python module into your current Python installation with:
 
 .. code-block:: bash
 
@@ -89,6 +89,29 @@ privileges) or into your personal Python module folder.
    Recompiling the shared library requires re-installing the Python
    package.
 
+.. _externally_managed:
+
+.. admonition:: Handling an "externally-managed-environment" Error
+   :class: Hint
+
+   Some Python installations made through Linux distributions
+   (e.g. Ubuntu 24.04LTS or later) will prevent installing the LAMMPS
+   Python module into a system folder or a corresponding folder of the
+   individual user as attempted by ``make install-python`` with an error
+   stating that an *externally managed* python installation must be only
+   managed by the same package package management tool.  This is an
+   optional setting, so not all Linux distributions follow it currently
+   (Spring 2025).  The reasoning and explanations for this error can be
+   found in the `Python Packaging User Guide
+   <https://packaging.python.org/en/latest/specifications/externally-managed-environments/>`_
+
+   These guidelines suggest to create a virtual environment and install
+   the LAMMPS Python module there (see below).  This is generally a good
+   idea and the LAMMPS developers recommend this, too.  If, however, you
+   want to proceed and install the LAMMPS Python module regardless, you
+   can install the "wheel" file (see above) manually with the ``pip``
+   command by adding the ``--break-system-packages`` flag.
+
 Installation inside of a virtual environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/src/Python_install.rst

@@ -110,13 +110,16 @@ folder that the dynamic loader searches or inside of the installed
 
       .. code-block:: bash
 
-         python install.py -p <python package> -l <shared library> -v <version.h file> [-n]
+         python install.py -p <python package> -l <shared library> -v <version.h file> [-n] [-f]
 
       * The ``-p`` flag points to the ``lammps`` Python package folder to be installed,
       * the ``-l`` flag points to the LAMMPS shared library file to be installed,
       * the ``-v`` flag points to the LAMMPS version header file to extract the version date,
-      * and the optional ``-n`` instructs the script to only build a wheel file
-        but not attempt to install it.
+      * the optional ``-n`` instructs the script to only build a wheel file but not attempt
+        to install it,
+      * and the optional ``-f`` argument instructs the script to force installation even if
+        pip would otherwise refuse installation with an
+        :ref:`error about externally managed environments <externally_managed>`.
 
    .. tab:: Virtual environment
 
@@ -198,6 +201,10 @@ folder that the dynamic loader searches or inside of the installed
 
          The ``PYTHONPATH`` needs to point to the parent folder that contains the ``lammps`` package!
 
+In case you run into an "externally-managed-environment" error when
+trying to install the LAMMPS Python module, please refer to
+:ref:`corresponding paragraph <externally_managed>` in the Python HOWTO
+page to learn about options for handling this error.
 
 To verify if LAMMPS can be successfully started from Python, start the
 Python interpreter, load the ``lammps`` Python module and create a

doc/src/Tools.rst

@@ -930,7 +930,7 @@ dependencies and redirects the download to the local cache.
 
    mkdir build
    cd build
-   cmake -D LAMMPS_DOWNLOADS_URL=${HTTP_CACHE_URL} -C "${LAMMPS_HTTP_CACHE_CONFIG}" -C ../cmake/presets/most.cmake ../cmake
+   cmake -D LAMMPS_DOWNLOADS_URL=${HTTP_CACHE_URL} -C "${LAMMPS_HTTP_CACHE_CONFIG}" -C ../cmake/presets/most.cmake -D DOWNLOAD_POTENTIALS=off ../cmake
    make -j 8
 
    deactivate_caches

doc/utils/sphinx-config/_static/up.png

@@ -137,6 +137,7 @@
           {# the master_doc variable was renamed to root_doc in Sphinx 4 (master_doc still exists in later Sphinx versions) #}
           {%- set _logo_url = logo_url|default(pathto('_static/' + (logo or ""), 1)) %}
           {%- set _root_doc = root_doc|default(master_doc) %}
+          <div id="sidebar-top-target"></div>
           <a href="{{ pathto(_root_doc) }}"{% if not theme_logo_only %} class="icon icon-home"{% endif %}>
             {% if not theme_logo_only %}{{ project }}{% endif %}
             {%- if logo or logo_url %}
@@ -172,6 +173,15 @@
         </div>
         {%- endblock %}
       </div>
+<!--      <div style="padding: 4px;">
+        <center>
+          <a href="#sidebar-top-target"><img src="_static/up.png" alt="(Up)"/> Go to top</a>
+        </center>
+      </div>
+-->
+    <div style="position: fixed; bottom: 0px; width: 300px; height: 64px; padding: 4px; background-color: #272525; text-align: center">
+      <a href="#sidebar-top-target" class="fa fa-caret-up" style="color: white"> Go to top</a>
+    </div>
     </nav>
 
     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

doc/utils/sphinx-config/_themes/lammps_theme/layout.html

@@ -288,7 +288,7 @@ rst_prolog = r"""
 
 .. only:: html
 
-   :math:`\renewcommand{\AA}{\textup{\r{A}}`
+   :math:`\renewcommand{\AA}{\text{Å}}`
 
 .. role:: lammps(code)
     :language: LAMMPS