Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use newtype idiom to generate Hyperbolic Space-specific matrix and vector types #264

Open
patowen opened this issue Feb 26, 2023 · 8 comments
Labels
enhancement New feature or request good first issue Good for newcomers

Comments

@patowen
Copy link
Collaborator

patowen commented Feb 26, 2023

To help avoid mistakes and make code easier to read and write, we should consider creating types to enforce the various invariants Hyperbolic vectors can have, much like nalgebra's Point vs. Vector vs. UnitVector types.

For example, we could have the following types (names subject to change):

  • HPoint: A vector that can represent a point in hyperbolic space. The invariant is x^2 + y^2 + z^2 < w^2 and w > 0.
  • HVector: A vector that can represent a direction in hyperbolic space. The invariant is x^2 + y^2 + z^2 > w^2.
  • NormalHPoint: A Lorentz-normalized HPoint. The invariant is x^2 + y^2 + z^2 - w^2 = -1 and w > 0.
  • NormalHVector: A Lorentz-normalized HVector. The invariant is x^2 + y^2 + z^2 - w^2 = 1.
  • HIsometry: A matrix representing an isometry in Hyperbolic space. All columns are Lorentz-orthogonal to each other. The first three columns are NormalHVectors, and the last column is a NormalHPoint.

Under normal use, it should be pretty easy to enforce these invariants. There can be convenient helper and impl functions for common operations and conversions. For exceptional cases, functions with unchecked in their name can be added to opt out of this extra safety.

@Ralith
Copy link
Owner

Ralith commented Feb 26, 2023

Let's continue the nalgebra convention and use HyperPoint and HyperVector rather than overloading "vector" further.

@patowen
Copy link
Collaborator Author

patowen commented Feb 26, 2023

I like that idea. I'll edit the description from HyperWVector to HyperPoint and from HyperXyzVector to HyperVector. If we for some reason need a single type that encompasses both (which I don't expect will happen), which originally would have been called HyperVector, we can just use a term like GeneralHyperVector instead.

@patowen
Copy link
Collaborator Author

patowen commented Feb 26, 2023

Another option is to call it HPoint, HVector, UnitHPoint, UnitHVector, and HIsometry to keep things shorter. There's already an HPoint in math.rs, but it isn't used anywhere, so it would make sense to replace it.

@Ralith
Copy link
Owner

Ralith commented Feb 26, 2023

I like that concision. Given the broad scope of these types I think that's justified.

Another thought: for the "unit" types, would it make sense to represent w implicitly, since it's uniquely determined by the other components? Also, to avoid confusion with vectors of unit length, would it make sense to name them differently (perhaps LorentzHPoint)?

@patowen
Copy link
Collaborator Author

patowen commented Feb 26, 2023

My first inclination would be to say that w should not be implicit. It cannot be implicit in UnitHVector because it can be positive or negative, and for UnitHPoint, if we need to find w, it requires a square-root operation, which is expensive enough that one would be tempted to use an HPoint instead, reducing safety.

For the unit type, it might make sense to use NormalizedHPoint. There isn't really any situation where it makes sense to take the Euclidean length of one of these vector types, so I believe using a term like Lorentz would be redundant and wouldn't clarify that it's Lorentz-normalized. I do agree that the term "unit vector" doesn't really make sense here, so I'm down to switch the language to "normalized vector".

@Ralith
Copy link
Owner

Ralith commented Feb 27, 2023

SGTM. Maybe "Normal" for concision.

@patowen
Copy link
Collaborator Author

patowen commented Feb 27, 2023

That makes sense to me. "normal" means a lot of things in math, so there is the risk of confusing it with surface normals, but I think the benefits of that concision outweigh this risk. I'll edit the issue description.

@Ralith Ralith added the good first issue Good for newcomers label Jan 11, 2024
@patowen
Copy link
Collaborator Author

patowen commented Jun 21, 2024

If we're careful, we may be able to use the proper mathematical terms for things, which may help for people who want to google things. For instance, we could lean into the "Minkowski" terminology and use something like MVector. Whenever we want to take a transpose, we could take the "Hermitian Adjoint" instead (probably can be shortened to adjoint). I don't know the best term for "orthogonal matrix" that could apply to Minkowski space, but I think "unitary" is the right term (https://en.wikipedia.org/wiki/Unitary_operator).

This could also potentially reopen the "unit" vs "normal" question, since it seems likely that Minkowski space already would have a term for vectors whose Minkowski product with themselves is 1 or -1. Based on https://en.wikipedia.org/wiki/Minkowski_space#Pseudo-Euclidean_metrics, the answer might be that "unit vector" is the right term after all, and we would use the term "space" and "time" to distinguish between the two types of unit vector.

This would give us something like MVector, MSpaceVector, MTimeVector, UnitMSpaceVector, UnitMTimeVector, and MUnitaryTransform (or possibly shortening it to MIsometry, since inner-product-preserving transformations should probably be able to be referred to as isometries).

Fortunately, renaming things is easy, so this can be decided later.

patowen pushed a commit that referenced this issue Jul 28, 2024
Partial fix for #264

Adds `MVector` in math.rs generally for points and directions in hyperbolic space, replacing `na::Vector4` when appropriate
Adds `MIsometry` in math.rs representing hyperbolic isometries, replacing `na::Matrix4` when appropriate

Authored-by: strawberry <redesignyourlogo@protonmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request good first issue Good for newcomers
Projects
None yet
Development

No branches or pull requests

2 participants