diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in index 48f456f6d6a..fadf4eb6898 100644 --- a/doc/doxygen/Doxyfile.in +++ b/doc/doxygen/Doxyfile.in @@ -2,7 +2,7 @@ DOXYFILE_ENCODING = UTF-8 PROJECT_NAME = "LAMMPS Programmer's Guide" -PROJECT_NUMBER = "10 December 2025" +PROJECT_NUMBER = "11 February 2026" PROJECT_BRIEF = "Documentation of the LAMMPS library interface and Python wrapper" PROJECT_LOGO = lammps-logo.png CREATE_SUBDIRS = NO diff --git a/doc/src/Manual_version.rst b/doc/src/Manual_version.rst index 0c757fc0ea0..aec51f367b0 100644 --- a/doc/src/Manual_version.rst +++ b/doc/src/Manual_version.rst @@ -79,10 +79,11 @@ About once a year, we release a *stable release* version of LAMMPS. This is done after a "stabilization period" where we apply only bug fixes and small, non-intrusive changes to the *develop* branch but no new features to the core code. At the same time, the code is subjected -to more detailed and thorough manual testing than the default automated -testing. After such a *stable release*, both the *release* and the -*stable* branches are updated and two tags are applied, a -``patch_1May2014`` format and a ``stable_1May2014`` format tag. +to more detailed and thorough manual testing that goes beyond the +automated testing done by default. After such a *stable release*, both +the *release* and the *stable* branches are updated and two tags are +applied, a ``patch_1May2014`` format and a ``stable_1May2014`` format +tag. Stable Release Updates """""""""""""""""""""" @@ -92,4 +93,5 @@ back-ported from the *develop* branch in a branch called *maintenance*. From the *maintenance* branch we make occasional *stable update releases* and update the *stable* branch accordingly. The first update to the ``stable_1May2014`` release would be tagged as -``stable_1May2014_update1``. These updates contain no new features. +``stable_1May2014_update1``. These updates contain no new features +and are intended to be fully backward compatible. diff --git a/doc/utils/sphinx-config/_static/favicon.ico b/doc/utils/sphinx-config/_static/favicon.ico new file mode 100644 index 00000000000..cce156bf799 Binary files /dev/null and b/doc/utils/sphinx-config/_static/favicon.ico differ diff --git a/src/citeme.h b/src/citeme.h index 7b1c6b8ef8f..d6ac3acecc2 100644 --- a/src/citeme.h +++ b/src/citeme.h @@ -53,7 +53,8 @@ that implements a published method or algorithm. \endverbatim - * \param reference String containing the citation in BibTeX format with DOI header */ + * + * \param reference String containing the citation in BibTeX format with DOI header */ void add(const std::string &reference); /** Flush accumulated citation buffers to screen and log file diff --git a/src/label_map.h b/src/label_map.h index a0a08c3b823..2ac5f8e7a9b 100644 --- a/src/label_map.h +++ b/src/label_map.h @@ -58,7 +58,8 @@ class LabelMap : protected Pointers { * \param nangletypes Number of angle types in map * \param ndihedraltypes Number of dihedral types in map * \param nimpropertypes Number of improper types in map */ - LabelMap(LAMMPS *lmp, int, int, int, int, int); + LabelMap(LAMMPS *lmp, int natomtypes, int nbondtypes, int nangletypes, int ndihedraltypes, + int nimpropertypes); ~LabelMap() override; /*! Process labelmap command from input script @@ -72,7 +73,7 @@ Add or modify type label mappings from the LAMMPS * * \param narg Number of arguments * \param arg Array of argument strings */ - void modify_lmap(int, char **); + void modify_lmap(int narg, char **arg); /*! Copy another LabelMap into this one * @@ -87,7 +88,7 @@ Currently used when combining data from multiple sources with * * \param lmap Pointer to source LabelMap * \param mode Merge mode flag */ - void merge_lmap(LabelMap *, int); + void merge_lmap(LabelMap *lmap, int mode); /*! Create index mapping between two LabelMaps * @@ -96,7 +97,7 @@ Currently used when combining data from multiple sources with * * \param lmap Pointer to source LabelMap * \param mode Mapping mode flag */ - void create_lmap2lmap(LabelMap *, int); + void create_lmap2lmap(LabelMap *lmap, int mode); /*! Find numeric type from type label * @@ -146,7 +147,7 @@ Currently used when combining data from multiple sources with * \return Bond type index if types match in the specified order, * negative bond type index if types match in reverse order, * 0 if there is no match found */ - int infer_bondtype(int, int); + int infer_bondtype(int atype1, int atype2); /*! Infer bond type from atom type labels * @@ -158,7 +159,7 @@ Currently used when combining data from multiple sources with * \return Bond type index if types match in the specified order, * negative bond type index if types match in reverse order, * 0 if there is no match found */ - int infer_bondtype(const std::vector &); + int infer_bondtype(const std::vector &labels); /*! Infer angle type from three numeric atom types * @@ -171,7 +172,7 @@ Currently used when combining data from multiple sources with * \return Angle type index if types match in the specified order, * negative angle type index if types match in reverse order, * 0 if there is no match found */ - int infer_angletype(int, int, int); + int infer_angletype(int atype1, int atype2, int atype3); /*! Infer angle type from three atom type labels * @@ -183,7 +184,7 @@ Currently used when combining data from multiple sources with * \return Angle type index if types match in the specified order, * negative angle type index if types match in reverse order, * 0 if there is no match found */ - int infer_angletype(const std::vector &); + int infer_angletype(const std::vector &labels); /*! Infer dihedral type from four numeric atom types * @@ -197,7 +198,7 @@ Currently used when combining data from multiple sources with * \return Dihedral type index if types match in the specified order, * negative dihedral type index if types match in reverse order, * 0 if there is no match found */ - int infer_dihedraltype(int, int, int, int); + int infer_dihedraltype(int atype1, int atype2, int atype3, int atype4); /*! Infer dihedral type from atom type labels * @@ -209,7 +210,7 @@ Currently used when combining data from multiple sources with * \return Dihedral type index if types match in the specified order, * negative dihedral type index if types match in reverse order, * 0 if there is no match found */ - int infer_dihedraltype(const std::vector &); + int infer_dihedraltype(const std::vector &labels); /*! Infer improper type from four numeric atom types * @@ -224,7 +225,8 @@ Currently used when combining data from multiple sources with * \return Improper type index if types match in the specified order, * negative improper type index if types match but different order, * 0 if there is no match found */ - int infer_impropertype(int, int, int, int, std::array *iorder = nullptr); + int infer_impropertype(int atype1, int atype2, int atype3, int atype4, + std::array *iorder = nullptr); /*! Infer improper type from atom type labels * @@ -237,7 +239,8 @@ Currently used when combining data from multiple sources with * \return Improper type index if types match in the specified order, * negative improper type index if types match but different order, * 0 if there is no match found */ - int infer_impropertype(const std::vector &, std::array *iorder = nullptr); + int infer_impropertype(const std::vector &labels, + std::array *iorder = nullptr); /*! @} */ @@ -246,11 +249,11 @@ Currently used when combining data from multiple sources with * Split a hyphen-delimited label (e.g., "C-N-H") into individual type strings. * Validates that the number of components matches the expected count. * - * \param ntypes Expected number of components - * \param label Hyphen-delimited label string - * \param types Output vector to store component strings - * \return 0 on success, -1 if component count doesn't match ntypes */ - int parse_typelabel(int, const std::string &, std::vector &); + * \param ntypes Expected number of components + * \param label Hyphen-delimited label string + * \param[out] types Output vector to store component strings + * \return 0 on success, -1 if component count doesn't match ntypes */ + int parse_typelabel(int ntypes, const std::string &label, std::vector &types); /*! \name I/O methods for label map persistence * @{ */ @@ -260,7 +263,7 @@ Currently used when combining data from multiple sources with * Output all type labels as sections to a LAMMPS data file. * * \param fp File pointer for writing */ - void write_data(FILE *); + void write_data(FILE *fp); /*! Read label map from restart file * @@ -284,11 +287,11 @@ Currently used when combining data from multiple sources with atypelabel; //!< Label storage (atoms, bonds, angles) std::vector dtypelabel, itypelabel; //!< Label storage (dihedrals, impropers) - std::unordered_map typelabel_map; //!< Atom label → type mapping - std::unordered_map btypelabel_map; //!< Bond label → type mapping - std::unordered_map atypelabel_map; //!< Angle label → type mapping - std::unordered_map dtypelabel_map; //!< Dihedral label → type mapping - std::unordered_map itypelabel_map; //!< Improper label → type mapping + std::unordered_map typelabel_map; //!< Atom label -> type mapping + std::unordered_map btypelabel_map; //!< Bond label -> type mapping + std::unordered_map atypelabel_map; //!< Angle label -> type mapping + std::unordered_map dtypelabel_map; //!< Dihedral label -> type mapping + std::unordered_map itypelabel_map; //!< Improper label -> type mapping /*! \struct Lmap2Lmap * \brief Mapping structure between two LabelMaps @@ -307,16 +310,51 @@ Currently used when combining data from multiple sources with Lmap2Lmap lmap2lmap; //!< Instance of inter-map translation data void reset_type_labels(); //!< Clear all type labels - int find_or_create( - const std::string &, std::vector &, - std::unordered_map &); //!< Look up type or create new type - int search(const std::string &, - const std::unordered_map &) const; //!< Look up type index - char *read_string(FILE *); //!< Read string from binary file - void write_string(const std::string &, FILE *); //!< Write string to binary file - int read_int(FILE *); //!< Read integer from binary file - - void write_map(const std::string &); //!< Write label map to file for debugging + + /*! Look up type label with given name or create new label if it doesn't exist + + * \param mylabel string with type label + * \param[in,out] labels list of type labels + * \param[in,out] labels_map label to numeric type hash table + * \return numeric type + */ + int find_or_create(const std::string &mylabel, std::vector &labels, + std::unordered_map &labels_map); + + /*! Look up numeric type of type label string in type map + * + * \param mylabel type label + * \param labels_map label to type map + * \return numeric type or -1 if not found */ + int search(const std::string &mylabel, + const std::unordered_map &labels_map) const; + + /*! Read a C-style string from a binary file and broadcast to world communicator + * + * the string buffer is allocated with new and must be freed by the calling code with delete[] + * + * \param fp FILE pointer of the openend file + * \return pointer to the allocated string buffer */ + char *read_string(FILE *fp); + + /*! Encode string to binary file. + * + * Must be only called from MPI rank 0. + * + * \param str string to write to the file + * \param fp FILE pointer of the opened file */ + void write_string(const std::string &str, FILE *fp); + + /*! Read integer from binary file and broadcast it to world communicator + * + * \param fp FILE pointer of the opened file + * \return integer value read from file */ + int read_int(FILE *fp); + + /*! Write out current label maps to a file for debugging + * + * \param filename file name */ + void write_map(const std::string &filename); }; } // namespace LAMMPS_NS diff --git a/src/platform.h b/src/platform.h index 47d08d8c458..3a00e17975a 100644 --- a/src/platform.h +++ b/src/platform.h @@ -256,12 +256,12 @@ std::string find_exe_path(const std::string &cmd); int chdir(const std::string &path); -/*! Create a directory +/*! Create a directory or directory path * - * Unlike the the ``mkdir()`` or ``_mkdir()`` functions of the - * C library, this function will also try to create non-existing sub-directories - * in case they don't exist, and thus behaves like the ``mkdir -p`` command rather - * than plain ``mkdir`` or ``md`. + * Unlike the the ``mkdir()`` or ``_mkdir()`` functions of the C library, this + * function will also try to create non-existing sub-directories in case they + * don't exist, and thus it behaves like the ``mkdir -p`` command rather than + * plain ``mkdir`` or ``md`` in a Unix or Windows shell, respectively. * * \param path directory path * \return -1 if unsuccessful, otherwise >= 0 */ diff --git a/src/utils.h b/src/utils.h index a5c84ef3bb9..d8f7c32f52a 100644 --- a/src/utils.h +++ b/src/utils.h @@ -426,13 +426,14 @@ tagint tnumeric(const char *file, int line, const char *str, bool do_abort, LAMM * - a single asterisk followed by a number, \*i: nlo = nmin; nhi = i; * - two numbers with an asterisk in between. i\*j: nlo = i; nhi = j; * + * \tparam TYPE the type of the index that is subject to the wildcard expansion * \param file name of source file for error message * \param line line number in source file for error message * \param str string to be processed * \param nmin smallest possible lower bound * \param nmax largest allowed upper bound - * \param nlo lower bound - * \param nhi upper bound + * \param[out] nlo lower bound + * \param[out] nhi upper bound * \param error pointer to Error class for out-of-bounds messages * \param failed argument index with failed expansion (optional) */ @@ -452,13 +453,14 @@ This functions adds the following case to :cpp:func:`utils::bounds() -std::string join(const std::vector &values, const std::string &sep); +template std::string join(const std::vector &values, const std::string &sep); /*! Take list of words and join them with a given separator text. *