Clarify documentation for libcasm.xtal.Lattice.is_equivalent_to

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to `libcasm-xtal` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- Clarified documentation for `libcasm.xtal.Lattice.is_equivalent_to`
+
 
 ## [2.0a9] - 2024-03-13
 

python/doc/conf.py

@@ -8,7 +8,11 @@
 logo_text = "libcasm-xtal"
 github_url = "https://github.com/prisms-center/CASMcode_crystallography/"
 pypi_url = "https://pypi.org/project/libcasm-xtal/"
-intersphinx_libcasm_packages = [("global", "2.0"), ("configuration", "2.0")]
+intersphinx_libcasm_packages = [
+    ("global", "2.0"),
+    ("configuration", "2.0"),
+    ("mapping", "2.0"),
+]
 
 
 # -- CASM common configuration ---

python/src/xtal.cpp

@@ -1193,19 +1193,28 @@ PYBIND11_MODULE(_xtal, m) {
            "True if lattice vectors are approximately equal")
       .def(py::self != py::self,
            "True if lattice vectors are not approximately equal")
-      .def("is_equivalent_to", &lattice_is_equivalent_to, py::arg("other"),
+      .def("is_equivalent_to", &lattice_is_equivalent_to, py::arg("lattice2"),
            R"pbdoc(
             Check if this lattice is equivalent to another lattice
 
-            Two lattices, L1 and L2, are equivalent (i.e. have the same
-            lattice points) if there exists `U` such that:
+            Two lattices, L1 and L2, are equivalent in the sense that the
+            lattice points have the same Cartesian coordinates if there exists
+            `U` such that:
 
             .. code-block:: Python
 
                 L1 = L2 @ U,
 
-            where `L1` and `L2` are the lattice vectors as matrix columns, and
-            `U` is a unimodular matrix (integer matrix, with abs(det(U))==1).
+            where `L1` and `L2` are the Cartesian lattice vectors as matrix
+            columns, and `U` is a unimodular matrix (integer matrix, with
+            abs(det(U))==1).
+
+            Notes
+            -----
+
+            - Use :func:`libcasm.mapping.methods.map_lattices` to check if
+              lattices are equivalent in the sense that a rigid rotation can
+              map the Cartesian coordinates of one lattice onto the other.
 
             Parameters
             ----------
@@ -1215,7 +1224,10 @@ PYBIND11_MODULE(_xtal, m) {
             Returns
             -------
             is_equivalent: bool
-                True if self is equivalent to `lattice2`.
+                True if `self`, with lattice vectors `L1`, is equivalent to
+                `lattice2`, with lattice vectors `L2`, in the sense that
+                the lattice points have the same Cartesian coordinates; False
+                otherwise.
             )pbdoc")
       .def("is_superlattice_of", &is_superlattice_of, py::arg("lattice2"),
            R"pbdoc(