Repository: sympy/sympy

Issue:
Why is the Quaternion logarithmic map given a private-looking name?
Why is `Quaternion._ln` not given a name like `Quaternion.log` and documented as part of the public interface?

This was asked a while back, but it was tangential to the main topic and thus ignored:

> BTW, Is it any reason to avoid conventional `log` name for method. There is only `_ln`. Leading underscore in the method name may confuse since it looks like a private method. Maybe, adding `log = _ln` to the class definition makes sense.

_Originally posted by @vr050714 in https://github.com/sympy/sympy/issues/21576#issuecomment-855421034_

It seems odd to me, especially since `Quaternion.exp` is public. There are many use cases of quaternions where we wish to go between the Lie group and Lie algebra in both directions.

Discussion:
sympy-bot: :white_check_mark:

Hi, I am the [SymPy bot](https://github.com/sympy/sympy-bot). I'm here to help you write a release notes entry. Please read the [guide on how to write release notes](https://github.com/sympy/sympy/wiki/Writing-Release-Notes).



Your release notes are in good order.

Here is what the release notes will look like:
* algebras
  * Renamed the Quaternion logarithm from `_ln` to `log`. ([#26597](https://github.com/sympy/sympy/pull/26597) by [@jpreiss](https://github.com/jpreiss))

This will be added to https://github.com/sympy/sympy/wiki/Release-Notes-for-1.13.

<details><summary>Click here to see the pull request description that was parsed.</summary>

    <!-- Your title above should be a short description of what
    was changed. Do not include the issue number in the title. -->

    #### References to other Issues or PRs
    Fixes #26552 

    #### Brief description of what is fixed or changed
    Renamed the quaternion logarithm method from `Quaternion._ln` to `Quaternion.log`.

    #### Other comments
    Previously the quaternion logarithm was called `_ln()`.  This was confusing because the quaternion exponential was given a normal "public" name `exp()`. The logarithm is equally important and was documented equally well, but had a "private" name.

    Docstring updated to mirror that of `exp()`.

    Renamed to `log()` instead of `ln()` because in most math software, `log` refers to the natural logarithm.

    My own motivating interest in quaternion exp/log is the mappings between the Lie group SO(3) and its Lie algebra so(3) when using the unit quaternion double-covering to represent SO(3). In this context, logarithm bases other than *e* never occur. I would guess this is the most common use of quaternion exp/log, but I am not sure.

    Not sure if we want to add a `_ln()` alias to avoid breaking old code? Or if it can be skipped because callers should not rely on methods that start with an underscore? Please advise.

    #### Release Notes

    <!-- Write the release notes for this release below between the BEGIN and END
    statements. The basic format is a bulleted list with the name of the subpackage
    and the release note for this PR. For example:

    * solvers
      * Added a new solver for logarithmic equations.

    * functions
      * Fixed a bug with log of integers. Formerly, `log(-x)` incorrectly gave `-log(x)`.

    * physics.units
      * Corrected a semantical error in the conversion between volt and statvolt which
        reported the volt as being larger than the statvolt.

    or if no release note(s) should be included use:

    NO ENTRY

    See https://github.com/sympy/sympy/wiki/Writing-Release-Notes for more
    information on how to write release notes. The bot will check your release
    notes automatically to see if they are formatted correctly. -->

    <!-- BEGIN RELEASE NOTES -->
    * algebras
      * Renamed the Quaternion logarithm from `_ln` to `log`.
    <!-- END RELEASE NOTES -->


</details><p>


Patch:
diff --git a/.mailmap b/.mailmap
index 2d81b1d8db..e5e40328d6 100644
--- a/.mailmap
+++ b/.mailmap
@@ -718,6 +718,7 @@ Jaime R <38530589+Jaime02@users.noreply.github.com>
 Jaime Resano <gemailpersonal02@gmail.com>
 Jainul Vaghasia <jainulvaghasia@gmail.com> <jainulvaghasia@D-10-157-53-226.dhcp4.washington.edu>
 Jakub Wilk <jwilk@jwilk.net>
+James A. Preiss <jamesalanpreiss@gmail.com> jpreiss <jamesalanpreiss@gmail.com>
 James Abbatiello <abbeyj@gmail.com>
 James Aspnes <aspnes@cs.yale.edu>
 James Brandon Milam <jmilam343@gmail.com>
diff --git a/sympy/algebras/quaternion.py b/sympy/algebras/quaternion.py
index ee03b7503f..3251d92af3 100644
--- a/sympy/algebras/quaternion.py
+++ b/sympy/algebras/quaternion.py
@@ -972,22 +972,22 @@ def exp(self):
 
         return Quaternion(a, b, c, d)
 
-    def _ln(self):
-        """Returns the natural logarithm of the quaternion (_ln(q)).
+    def log(self):
+        r"""Returns the logarithm of the quaternion, given by $\log q$.
 
         Examples
         ========
 
         >>> from sympy import Quaternion
         >>> q = Quaternion(1, 2, 3, 4)
-        >>> q._ln()
+        >>> q.log()
         log(sqrt(30))
         + 2*sqrt(29)*acos(sqrt(30)/30)/29*i
         + 3*sqrt(29)*acos(sqrt(30)/30)/29*j
         + 4*sqrt(29)*acos(sqrt(30)/30)/29*k
 
         """
-        # _ln(q) = _ln||q|| + v/||v||*arccos(a/||q||)
+        # log(q) = log||q|| + v/||v||*arccos(a/||q||)
         q = self
         vector_norm = sqrt(q.b**2 + q.c**2 + q.d**2)
         q_norm = q.norm()


Test patch:
diff --git a/sympy/algebras/tests/test_quaternion.py b/sympy/algebras/tests/test_quaternion.py
index 8215635c83..87b68f54b5 100644
--- a/sympy/algebras/tests/test_quaternion.py
+++ b/sympy/algebras/tests/test_quaternion.py
@@ -172,7 +172,7 @@ def test_quaternion_functions():
                2 * sqrt(29) * E * sin(sqrt(29)) / 29,
                3 * sqrt(29) * E * sin(sqrt(29)) / 29,
                4 * sqrt(29) * E * sin(sqrt(29)) / 29)
-    assert q1._ln() == \
+    assert q1.log() == \
     Quaternion(log(sqrt(30)),
                2 * sqrt(29) * acos(sqrt(30)/30) / 29,
                3 * sqrt(29) * acos(sqrt(30)/30) / 29,