Usage Guide

This guide demonstrates how to use coordinax.api to implement custom vector types and coordinate transformations that integrate with the coordinax ecosystem.

The coordinax.api package uses plum-dispatch for multiple dispatch. This allows different implementations of the same function based on the types of the arguments.

Representations

Here’s how to create a custom 2D vector type and implement coordinate transformations:

import math
import dataclasses
import plum

import coordinax.api.representations as cxrapi


@dataclasses.dataclass
class MyCartesian:
    """A simple 2D vector in Cartesian coordinates."""

    x: float
    y: float


@dataclasses.dataclass
class MyPolar:
    """A simple 2D vector in polar coordinates."""

    r: float
    theta: float


# Implement conversion from Cartesian to Polar
@plum.dispatch
def cconvert(vec: MyCartesian, target: type[MyPolar], **kwargs):
    """Convert Cartesian to polar coordinates."""
    r = math.sqrt(vec.x**2 + vec.y**2)
    theta = math.atan2(vec.y, vec.x)
    return MyPolar(r=r, theta=theta)


# Implement conversion from Polar to Cartesian
@plum.dispatch
def cconvert(vec: MyPolar, target: type[MyCartesian], **kwargs):
    """Convert polar to Cartesian coordinates."""
    x = vec.r * math.cos(vec.theta)
    y = vec.r * math.sin(vec.theta)
    return MyCartesian(x=x, y=y)


# Usage
cart = MyCartesian(x=3.0, y=4.0)
polar = cxrapi.cconvert(cart, MyPolar)
print(f"Polar: r={polar.r:.2f}, theta={polar.theta:.2f}")  # r=5.00, theta=0.93

back = cxrapi.cconvert(polar, MyCartesian)
print(f"Cartesian: x={back.x:.2f}, y={back.y:.2f}")  # x=3.00, y=4.00

Best Practices

1. Type hints: Always use proper type hints for dispatch to work correctly

2. Documentation: Document what your dispatch expects and returns

3. Error handling: Raise clear errors for unsupported conversions

4. Testing: Test your dispatches with various input types

Next Steps

• See the API Reference for complete documentation

• Check out the coordinax documentation for concrete implementations

• Review the plum-dispatch documentation for advanced dispatch patterns