✅

Hi, I am the SymPy bot (v161). I'm here to help you write a release notes entry. Please read the guide on how to write release notes.

Your release notes are in good order.

Here is what the release notes will look like:

• algebras
  • quaternion (#20853 by @mayankray2020)

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

<!-- 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
<!-- If this pull request fixes an issue, write "Fixes #NNNN" in that exact
format, e.g. "Fixes #1234" (see
https://tinyurl.com/auto-closing for more information). Also, please
write a comment on that issue linking back to this pull request once it is
open. -->
Fixes #20769 


#### Brief description of what is fixed or changed
Added the features mentioned in #20769

<!-- BEGIN RELEASE NOTES -->
* algebras
  * quaternion
<!-- END RELEASE NOTES -->

@oscarbenjamin please review

@danilobellini can you review this?

@danilobellini please review

@danilobellini @oscarbenjamin I've made the suggested changes. Please review it.

There's no need to replace everything just to use is_pure instead of checking if self.a == 0 or something alike. The zero quaternion is orthogonal and parallel to every other quaternion at the same time, and the "ternary coplanar" (or axis coplanar) also makes sense for the zero quaternion (from the description of my previous review). There are only two cases where the quaternion zero should be really handled: (1) for the is_pure, to tell that "zero" isn't a right/pure quaternion (it might be, but it's really undefined, and returning False makes sense, and the first updated assert is already verifying this), (2) the binary coplanarity (quaternion planes), which is undefined if the axis is undefined (so it should handle not just the zero but all zero-axis inputs).

In Quaternion.coplanar there are some double checks on a, and the and/or/and pattern looks confusing (which comes first?). Binary coplanarity is undefined if an input has an undefined axis, it makes sense to raise ValueError unless self.vector().is_pure() and the same for the otherinput.

The Quaternion.ternary_coplanar implementation, as well as orthogonal and parallel, might just check if a is zero, they still make sense otherwise (e.g. defining orthogonality as something like "dot product is zero" we would get the same result).

I'm not aware of how some internal automation of Sympy works, but I know sometimes I need to explicitly tell Sympy to expand/simplify/... an expression to get a straight result like "these two are indeed the same". I don't know if just checking (code) == 0 is better than code.simplify() == 0 or something alike using Eq or something else "internal". Even the or, when should it be used, and when the | operator should be used? For stuff like that, as well as code style, I think someone else should review.

Actually in the definition Quaternion_ternanry_coplanar() it is said that it works for pure quaternions, but the 0 quaternion is not called pure so is that right if we allow Quaternion_ternanry_coplanar() to work for 0 'Quatertion'?

Actually in the definition Quaternion_ternanry_coplanar() it is said that it works for pure quaternions, but the 0 quaternion is not called pure so is that right if we allow Quaternion_ternanry_coplanar() to work for 0 'Quatertion'?

Since ternary_coplanar(), orthogonal() and parallel() are applied on "quaternions without real part seen as 3D vectors", zero makes some sense for them. Coplanarity means that the vectors (or the points and the origin) are in the same plane, that always happens for 3 vectors if one of them is zero. Orthogonality with that multiplication definition is like "dot product is zero", which makes zero orthogonal to all vectors. Parallelism defined as "one vector is a multiple of another" also makes zero parallel to every vector, and that's what happens with the multiplication definition.

By definition, Hamilton used the expression "right quaternion" to denote what we call "pure quaternion" nowadays. He uses "right" to mean that its angle is pi/2, something that happens for all quaternions whose real part is zero, but the zero quaternion, whose angle is undefined. However, "undefined" means neither "zero is a right quaternion" nor "zero isn't right quaternion", it just means that we don't know, it depends on something external (the context and/or how we use it).

When we are using quaternions as 3D vectors (with their real part equals to zero), our context makes zero a right/pure quaternion (one can think on it as a limit, where everything else in the domain has angle equals to pi/2).

When we are using unit quaternions (versors), they are like grand circle arcs in a specific plane but without a specific "position" in the circle, because we can interpret it as a rotation operator in that plane, multiplying it at left (that is, in OB/OA * OA we can regard the division OB/OA as the rotation quaternion that takes OA and "moves" it to OB, where O is the origin, A and B are points in the 3D unit sphere). In the multiplication we have two "natures" of quaternions: what matters for "OB/OA" is the quaternion plane (which contains OB and OA), for OA we don't have a real part (as it's a 3D vector). We can extend it to be not just a grand circle arc, but also a scale factor, an arc obtained with a linear interpolation of the angle and a logarithmic interpolation of the radius (like what happens with the multiplication of complex numbers). In this case, the magnitude of OA doesn't need to be 1. The "binary coplanar" is applied on quaternions like "OB/OA", whereas the "ternary coplanar" is applied on 3D vectors written as quaternions like "OA". If "OA" is zero, we won't be able to build a quaternion like "OB/OA", but "OA" is still interpreted as a 3D vector, hence its angle is still seen as pi/2 (due to the context). But if "OB" is zero, "OB/OA" still makes sense, but its angle is undefined, it's the angle from OA to OB in their plane, but we can't even define a single plane in this case, as happens when OA and OB are in the same line. In such case, coplanarity can't be evaluated between a quaternion and "OB/OA" since the quaternion doesn't know the direction of the 3D vectors OB and OA, and that's not just for the zero quaternion case but for all cases where the imaginary part is zero.

Actually in the definition Quaternion_ternanry_coplanar() it is said that it works for pure quaternions, but the 0 quaternion is not called pure so is that right if we allow Quaternion_ternanry_coplanar() to work for 0 'Quatertion'?

Since ternary_coplanar(), orthogonal() and parallel() are applied on "quaternions without real part seen as 3D vectors", zero makes some sense for them. Coplanarity means that the vectors (or the points and the origin) are in the same plane, that always happens for 3 vectors if one of them is zero. Orthogonality with that multiplication definition is like "dot product is zero", which makes zero orthogonal to all vectors. Parallelism defined as "one vector is a multiple of another" also makes zero parallel to every vector, and that's what happens with the multiplication definition.

By definition, Hamilton used the expression "right quaternion" to denote what we call "pure quaternion" nowadays. He uses "right" to mean that its angle is pi/2, something that happens for all quaternions whose real part is zero, but the zero quaternion, whose angle is undefined. However, "undefined" means neither "zero is a right quaternion" nor "zero isn't right quaternion", it just means that we don't know, it depends on something external (the context and/or how we use it).

When we are using quaternions as 3D vectors (with their real part equals to zero), our context makes zero a right/pure quaternion (one can think on it as a limit, where everything else in the domain has angle equals to pi/2).

When we are using unit quaternions (versors), they are like grand circle arcs in a specific plane but without a specific "position" in the circle, because we can interpret it as a rotation operator in that plane, multiplying it at left (that is, in OB/OA * OA we can regard the division OB/OA as the rotation quaternion that takes OA and "moves" it to OB, where O is the origin, A and B are points in the 3D unit sphere). In the multiplication we have two "natures" of quaternions: what matters for "OB/OA" is the quaternion plane (which contains OB and OA), for OA we don't have a real part (as it's a 3D vector). We can extend it to be not just a grand circle arc, but also a scale factor, an arc obtained with a linear interpolation of the angle and a logarithmic interpolation of the radius (like what happens with the multiplication of complex numbers). In this case, the magnitude of OA doesn't need to be 1. The "binary coplanar" is applied on quaternions like "OB/OA", whereas the "ternary coplanar" is applied on 3D vectors written as quaternions like "OA". If "OA" is zero, we won't be able to build a quaternion like "OB/OA", but "OA" is still interpreted as a 3D vector, hence its angle is still seen as pi/2 (due to the context). But if "OB" is zero, "OB/OA" still makes sense, but its angle is undefined, it's the angle from OA to OB in their plane, but we can't even define a single plane in this case, as happens when OA and OB are in the same line. In such case, coplanarity can't be evaluated between a quaternion and "OB/OA" since the quaternion doesn't know the direction of the 3D vectors OB and OA, and that's not just for the zero quaternion case but for all cases where the imaginary part is zero.

I've made the suggested changes and for the confusion in and, or in the coplanar I've added brackets to make it more clear.

@oscarbenjamin @danilobellini @oscargus please review this.

@oscarbenjamin please review.

All of the docstrings here need more explanation. Each concept should be defined. The definitions can refer to the other concepts provided they also reference them in a "see also" section. The "Returns" and "parameters" sections should be more consistent. They should specify the type of what is returned both as a Python type and also as a mathematical type like Expr: real number representing the scalar part of the quaternion.

I don't know if you've already seen the style guide but it's here and gives examples of these things:
https://docs.sympy.org/latest/documentation-style-guide.html

All of the docstrings here need more explanation. Each concept should be defined. The definitions can refer to the other concepts provided they also reference them in a "see also" section. The "Returns" and "parameters" sections should be more consistent. They should specify the type of what is returned both as a Python type and also as a mathematical type like Expr: real number representing the scalar part of the quaternion.

I've made the suggested changes and made the doc strings bit more inofrmative. As mentioned here #20769 (comment) coplanar and ternary_coplanar have different meanings so I think it would be better to rename the method but should I allow them to take more inputs because if an user wants to check coplanarity for multiple quaternions, they can do it with 2 input coplanar method as well. What are your views on this @oscarbenjamin .

In general in sympy methods like is_pure usually use three-valued logic. The reason is that in the symbolic case where we have something like x + y*i we do not know if x or y is zero. The attribute is_zero is used for this (rather than == 0) and gives True, False or None with None meaning "unknown". The functions fuzzy_and etc are used to handle boolean arithmetic in three-valued logic. I wonder if all of the boolean methods here should be using three-valued logic.

@oscarbenjamin please review.

@oscarbenjamin please review.

@oscarbenjamin please review.

@danilobellini does this look good to you?

This needs better release notes.

About the item "Add Quaternion.versor() as a new name to Quaternion.normalize()", that can be done by a simple versor = normalize, but the most important part of that item is a documentation update, whose "explanation" section should describe it using the modern "hat" notation (\hat{q} in LaTeX), the equation q/|q|, and the classical Hamilton notation \mathbf{U}(q).

With "Add Hamilton operators to the Quaternion documentation" I was thinking on a new table (perhaps in the module/class docstring or elsewhere just for the rendering it all in the "Algebras" docs) summarizing Hamilton's notation and the modern notation where it makes sense. And, to avoid confusion with the names, the item "add the deprecated terminology 'norm' and 'tensor' to the documentation" was proposed, that could be part of that table or a single paragraph before/after it.

These items weren't tackled yet, but perhaps these 3 items (as well as some documentation-related parts of my last review) can be written as another PR (after this one is fixed/finished and merged).

Can i take up this PR and make the changes as mentioned above and open another PR for this ? since this PR seems to be stalled

Yes, but please preserve the commits (including the original author details) if you do that. Since this has merge conflicts I would do that by rebasing or cherrypicking the commits onto master.

This can be closed now as #22713 is merged.