feat: like method for projecting vector into the coordinate space of another vector + better type errors and hints

[Saransh-cpp]

Description

Xref: #422
Will rebase once #423 is merged.

Please describe the purpose of this pull request. Reference and link to any relevant issues or pull requests.

Checklist

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't any other open Pull Requests for the required change?
• Does your submission pass pre-commit? ($ pre-commit run --all-files or $ nox -s lint)
• Does your submission pass tests? ($ pytest or $ nox -s tests)
• Does the documentation build with your changes? ($ cd docs; make clean; make html or $ nox -s docs)
• Does your submission pass the doctests? ($ pytest --doctest-plus src/vector/ or $ nox -s doctests)

Before Merging

• Summarize the commit messages into a brief review of the Pull request.

[Saransh-cpp]

Hi @jpivarski, @nsmith-, @iasonkrom, @lgray

I've noticed that some operations require the vectors to be of different dimensions; for instance, boost_beta3 (the failing test).

Is there a specific set of operations that should error out when performed on vectors of different dimensionality, or maybe I should ask about a particular set of operations that should not error?

The like method and the TypeError are working well in this PR! (see tests)

[ikrommyd]

I would assume that those that require different dimensionality are fewer so.... the second option? Y'all may have better opinions though.

[codecov]

Codecov Report

Attention: Patch coverage is 72.28916% with 23 lines in your changes are missing coverage. Please review.

Project coverage is 82.81%. Comparing base (6574993) to head (ddad594).
Report is 1 commits behind head on main.

Files	Patch %	Lines
src/vector/_methods.py	72.28%	23 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #426      +/-   ##
==========================================
- Coverage   82.92%   82.81%   -0.12%     
==========================================
  Files          96       96              
  Lines       11533    11557      +24     
==========================================
+ Hits         9564     9571       +7     
- Misses       1969     1986      +17     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[nsmith-]

Some methods do require arguments of a particular type to be meaningful, such as LorentzVector.boost_beta3 should only accept a 3-component monentum vector.

[Saransh-cpp]

Some methods do require arguments of a particular type to be meaningful, such as LorentzVector.boost_beta3 should only accept a 3-component monentum vector.

Ah, this can be easily highlighted by updating the type signature, so I think an error in such situations will be redundant?

--- a/src/vector/_methods.py
+++ b/src/vector/_methods.py
@@ -3818,7 +3818,7 @@ class Lorentz(Spatial, VectorProtocolLorentz):
         return boost_p4.dispatch(self, p4)
 
     def boost_beta3(
-        self: SameVectorType, beta3: VectorProtocolSpatial
+        self: SameVectorType, beta3: MomentumProtocolSpatial
     ) -> SameVectorType:
         from vector._compute.lorentz import boost_beta3

[Saransh-cpp]

Thinking about this again, do we want strict checks in each method/operation or do we want strict checks only in the methods/operations that can accept every type of vector (v: VectorProtocol).

For instance, add has the following signature:

def add(self, other: VectorProtocol) -> VectorProtocol:

Therefore, I have added a type check in this method. But, cross has the following updated signature in this PR:

def cross(self, other: VectorProtocolSpatial) -> VectorProtocolSpatial:

and the following works:

In [1]: import vector

In [2]: vector.obj(x=0.1, y=0.2, z=0.3, t=10).cross(vector.obj(x=0.4, y=0.5, z=0.6, t=20))
Out[2]: VectorObject3D(x=-0.03, y=0.06, z=-0.030000000000000013)

From an API design point of view, should we check the type of an argument even after providing a type hint? It feels redundant to me. Maybe the implementation of cross should be changed such that it does not generalize to 4D vectors, instead of explicitly checking the type of the vectors before executing the logic.

cc: @jpivarski

[jpivarski]

The new like method is documented, but there should also be a short comment about it in the error messages that result from trying to add/subtract/compare vectors of different dimensionality, since the like method is how users would fix those errors.

The exclusion of implicit projection/embedding and inclusion of a new like method together form a single project of asking users for clarity about whether they want to project or embed. Some text like

x + y   →   x.like(y) + y   or   x + y.like(x)

would indicate where the user is being asked for their opinion.

[jpivarski]

This might be required for black-compliant formatting, but it makes what would be easy to read into something difficult to read.

Do you need the commas?

Suggested change

	v1 - v2.like(v1), v1.like(
	v2
	) - v2, v1 - v2.to_xyz(), v1.to_xy() - v2, v1 - v2.to_Vector3D(
	z=3
	), v1.to_Vector2D() - v2
	v1 - v2.like(v1)
	v1.like(v2) - v2
	v1 - v2.to_xyz()
	v1.to_xy() - v2
	v1 - v2.to_Vector3D(z=3)
	v1.to_Vector2D() - v2

Should there be some explanatory text between these?

[Saransh-cpp]

Thanks for the review, @jpivarski! The error message here displays the usage of the new like method. Should this be changed in any way?

[Saransh-cpp]

Re-requesting your review on this too, @jpivarski!

[jpivarski]

This is great! I approve!

Having a utility function for that error message is a good idea; it seems to be needed in a lot of methods.

[Saransh-cpp]

Great, thanks for the review!