coordinax.charts

Higher-order function for fixed-arg Jacobian point map.

>>> import coordinax.charts as cxc
>>> import unxt as u

>>> map = cxc.jac_pt_map(None, cxc.cart3d, cxc.sph3d, usys=u.unitsystems.si)
>>> at = {"x": u.Q(1.0, "m"), "y": u.Q(0.0, "m"), "z": u.Q(0.0, "m")}
>>> map(at)
QMatrix(
    [[ 1.,  0.,  0.],
     [-0., -0., -1.],
     [ 0.,  1.,  0.]],
    '((, , ), (rad / m, rad / m, rad / m), (rad / m, rad / m, rad / m))'
)

>>> import jax
>>> J = jax.vmap(map)(jax.tree.map(lambda x: x[None], at))
>>> J.shape
(1, 3, 3)

coordinax.charts.jac_pt_map(from_chart: AbstractChart, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None) → Callable[[object], Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Higher-order function for fixed-arg Jacobian point map.

>>> import coordinax.charts as cxc
>>> import unxt as u

>>> map = cxc.jac_pt_map(cxc.cart3d, cxc.sph3d, usys=u.unitsystems.si)
>>> at = {"x": u.Q(1.0, "m"), "y": u.Q(0.0, "m"), "z": u.Q(0.0, "m")}
>>> map(at)
QMatrix(
    [[ 1.,  0.,  0.],
     [-0., -0., -1.],
     [ 0.,  1.,  0.]],
    '((, , ), (rad / m, rad / m, rad / m), (rad / m, rad / m, rad / m))'
)

>>> import jax
>>> J = jax.vmap(map)(jax.tree.map(lambda x: x[None], at))
>>> J.shape
(1, 3, 3)

coordinax.charts.jac_pt_map(at: Array, from_chart: AbstractChart, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem) → Array

Parameters:

args (Any)
kwargs (Any)

Return type:

Compute the Jacobian at a plain-array base point.

Treats at as a flat numeric array whose elements are the from_chart coordinates expressed. Returns the JAX array Jacobian $J^j{}_i = partial tau^j / partial q^i$, without unit annotation.

>>> import jax.numpy as jnp
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> jac_fn = cxc.jac_pt_map(None, cxc.cart3d, cxc.sph3d, usys=u.unitsystems.si)

>>> at = jnp.array([1, 0, 0])
>>> jac_fn(at)
Array([[ 1.,  0.,  0.],
       [-0., -0., -1.],
       [ 0.,  1.,  0.]], dtype=float64)

>>> import jax
>>> J = jax.vmap(jac_fn)(at[None])
>>> J.shape
(1, 3, 3)

coordinax.charts.jac_pt_map(at: dict[str, Any], from_chart: AbstractChart, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → Array | QMatrix

Parameters:

args (Any)
kwargs (Any)

Return type:

Compute the Jacobian at a coordinate-dictionary base point.

The primary dict-input dispatch. Branches on whether the values of at carry physical units:

Array-valued branch (no units in any value): Stacks the dict values into a plain array via jnp.stack, then forwards to jac_pt_map(at_arr, from_chart, to_chart, usys=usys) which requires usys. For chart pairs without an analytical Array dispatch this means usys must be provided.
Quantity-valued branch (at least one value carries a unit): Packs at into a 1-D QMatrix via pack_to_qmatrix(at, keys=from_chart.components), promotes any integer or boolean leaves to the default floating-point dtype (other dtypes, including complex, are left unchanged and will raise a TypeError from jax.jacfwd if passed), then computes J_qq = jax.jacfwd(pt_map_fn)(at_in). Because jacfwd applied to a QMatrix-in / QMatrix-out function yields a nested QMatrix, _repack_q_from_jac is called to extract the correct 2-D unit structure.

Returns:

Plain array when at is array-valued; QMatrix of shape (n_out, n_in) with per-element units otherwise.

Return type:

Any

Raises:

ValueError – If at keys do not match from_chart.components (via check_data).
plum.NotFoundLookupError – If the array-valued branch cannot resolve a dispatch (e.g. generic chart pair with usys=None).

Parameters:

args (Any)
kwargs (Any)

Examples

>>> import coordinax.charts as cxc
>>> import unxt as u

Quantity-valued dict (no usys needed):

>>> at = {"x": u.Q(1.0, "m"), "y": u.Q(0.0, "m"), "z": u.Q(0.0, "m")}
>>> J = cxc.jac_pt_map(at, cxc.cart3d, cxc.sph3d)
>>> J.value.shape
(3, 3)

Plain-array dict (usys required):

>>> import jax.numpy as jnp
>>> at_arr = {"x": jnp.array(1.0), "y": jnp.array(0.0), "z": jnp.array(0.0)}
>>> J2 = cxc.jac_pt_map(at_arr, cxc.cart3d, cxc.sph3d, usys=u.unitsystems.si)
>>> J2.shape
(3, 3)

coordinax.charts.jac_pt_map(at: Array, from_chart: Cart2D, to_chart: Polar2D, /, *, usys: AbstractUnitSystem | None = None) → Array

Parameters:

args (Any)
kwargs (Any)

Return type:

Compute the Jacobian of the transition function between two charts.

$$ J = frac{partial(r,theta)}{partial(x,y)}

= ( x/r & y/r -y/r^2 & x/r^2 ) = ( costheta & sintheta -sintheta/r & costheta/r )

$$

>>> import coordinax.charts as cxc
>>> import unxt as u

>>> x = jnp.array([1.0, 1.0])
>>> cxc.jac_pt_map(cxc.cart2d, cxc.polar2d, usys=u.unitsystems.si)(x)
Array([[ 0.70710678,  0.70710678],
       [-0.5       ,  0.5       ]], dtype=float64)

coordinax.charts.jac_pt_map(at: AbstractQuantity, from_chart: Cart2D, to_chart: Polar2D, /, *, usys: AbstractUnitSystem | None = None) → QMatrix

Parameters:

args (Any)
kwargs (Any)

Return type:

Compute the Jacobian of the transition function between two charts.

$$ J = frac{partial(r,theta)}{partial(x,y)}

= ( x/r & y/r -y/r^2 & x/r^2 ) = ( costheta & sintheta -sintheta/r & costheta/r )

$$

>>> import coordinax.charts as cxc
>>> import unxt as u

>>> x = u.Q(jnp.array([1.0, 1.0]), "m")
>>> cxc.jac_pt_map(cxc.cart2d, cxc.polar2d, usys=u.unitsystems.si)(x)
QMatrix([[ 0.70710678,  0.70710678],
                [-0.5       ,  0.5       ]], '((, ), (rad / m, rad / m))')

Parameters:

args (Any)
kwargs (Any)

Return type:

coordinax.charts.pt_map(*args: Any, **kwargs: Any)#

Transform position coordinates from one chart to another.

This function implements the most general point-coordinate map between two compatible chart representations of the same geometric point. It is a point-wise map that preserves the physical location while changing the coordinate description.

For charts in the same atlas on the same manifold, this reduces to the ordinary chart transition map handled by pt_map. It is the intrinsic coordinate-change operation: the underlying point on the manifold is unchanged, and only its coordinate representation is changed.

However, this function is not restricted to two charts on the same manifold. It may also represent a realization-style map between charts attached to different manifolds when one is a realization of the other, such as an intrinsic chart on an embedded manifold and a chart on its ambient manifold. In that case, this function may change both the chart and the manifold in which the point is being represented.

Mathematical Definition:

Let $(U, varphi_{mathrm{from}})$ and $(V, varphi_{mathrm{to}})$ be charts on the same manifold $M$, with overlapping domains. The transition map is

$$: varphi_{mathrm{to}} circ varphi_{mathrm{from}}^{-1} : varphi_{mathrm{from}}(U cap V) to varphi_{mathrm{to}}(U cap V).

$$

If a point $p in U cap V$ has coordinates $q = varphi_{mathrm{from}}(p)$, then this function returns $p’ = varphi_{mathrm{to}}(p)$ for the same manifold point.

More generally, if $varphi_{mathrm{from}} : U subset M to mathbb{R}^n$ and $psi_{mathrm{to}} : W subset N to mathbb{R}^m$ are chart maps on manifolds $M$ and $N$, and there is a point map $F : M supset U to W subset N$, then pt_map represents the coordinate expression

$$ psi_{mathrm{to}} circ F circ varphi_{mathrm{from}}^{-1}. $$

3D Spherical → Cartesian:

$$
x &= r sintheta cosphi \ y &= r sintheta sinphi \ z &= r costheta

$$

Raises:

NotImplementedError – If no transformation rule is registered for the specific pair of charts (to_chart, from_chart).

Parameters:

args (Any)
kwargs (Any)

Return type:

Notes

This is a position-only transformation.
This function may map between charts on the same manifold or across manifolds, provided a compatible point map is defined between them.
Transformations preserve physical dimensions. For example, converting from polar to Cartesian preserves that r has length dimension and produces x and y with length dimension.
Some transformations may introduce singularities (e.g., polar coordinates at the origin, spherical coordinates at poles).
Transformations are composable: transforming $A to B to C$ yields the same result as a direct $A to C$ transformation (up to numerical precision).
Identity transformations (same from_chart and to_chart) return the input unchanged.

See also

pt_map: transform position coordinates between charts on the

same

Examples

>>> import quaxed.numpy as jnp
>>> import coordinax.charts as cxc
>>> import unxt as u

Transform from 2D polar to Cartesian:

>>> p_polar = {"r": u.Q(2.0, "m"), "theta": u.Angle(jnp.pi / 4, "rad")}
>>> cxc.pt_map(p_polar, cxc.polar2d, cxc.cart2d)
{'x': Q(1.41421356, 'm'), 'y': Q(1.41421356, 'm')}

Transform from 3D spherical to Cartesian:

>>> p_sph = {"theta": u.Angle(jnp.pi / 2, "rad"), "phi": u.Angle(0.0, "rad"),
...          "r": u.Q(5.0, "km")}
>>> cxc.pt_map(p_sph, cxc.sph3d, cxc.cart3d)
{'x': Q(5., 'km'), 'y': Q(0., 'km'), 'z': Q(3.061617e-16, 'km')}

Transform from Cartesian to cylindrical:

>>> p_xyz = {"x": u.Q(3.0, "m"), "y": u.Q(4.0, "m"), "z": u.Q(5.0, "m")}
>>> cxc.pt_map(p_xyz, cxc.cart3d, cxc.cyl3d)
{'rho': Q(5., 'm'), 'phi': Q(0.92729522, 'rad'), 'z': Q(5., 'm')}

coordinax.charts.pt_map(q: NoneType, /, *fixed_args: Any, **fixed_kw: Any) → Callable[..., Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Return a partial function for point transformation.

>>> import coordinax.charts as cxc
>>> import unxt as u

Coordinates without units are the default.

>>> q = {"x": u.Q(1.0, "m"), "y": u.Q(0.0, "m"), "z": u.Q(0.0, "m")}
>>> map = cxc.pt_map(None, cxc.cart3d, cxc.sph3d)
>>> map(q)
{'r': Q(1., 'm'), 'theta': Q(1.57079633, 'rad'), 'phi': Q(0., 'rad')}

Coordinates without units are also accepted, interpreted having units of the unxt.AbstractUnitSystem, which must be passed.

>>> q = {"x": 1.0, "y": 0.0, "z": 0.0}
>>> map = cxc.pt_map(None, cxc.cart3d, cxc.sph3d, usys=u.unitsystems.si)
>>> map(q)
{'r': Array(1., dtype=float64, ...),
 'theta': Array(1.57079633, dtype=float64),
 'phi': Array(0., dtype=float64, ...)}

unxt.Quantity inputs are also accepted, and are interpreted as being in Cartesian coordinates.

>>> p = u.Q([1.0, 0.0, 0.0], "m")
>>> map = cxc.pt_map(None, cxc.cart3d, cxc.sph3d)
>>> map(p)
QMatrix([1.        , 1.57079633, 0.        ], '(m, rad, rad)')

Array-Like inputs are interpreted as Cartesian coordinates with units from the required unxt.AbstractUnitSystem.

>>> q = [1.0, 0.0, 0.0]
>>> map = cxc.pt_map(None, cxc.cart3d, cxc.sph3d, usys=u.unitsystems.si)
>>> map(q)
Array([1.        , 1.57079633, 0.        ], dtype=float64)

coordinax.charts.pt_map(from_chart: AbstractChart, to_chart: AbstractChart, /, **fixed_kw: Any) → Callable[..., Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Return a partial function for point transformation.

>>> import coordinax.charts as cxc
>>> import unxt as u

Coordinates without units are the default.

>>> p = {"x": u.Q(1.0, "m"), "y": u.Q(0.0, "m"), "z": u.Q(0.0, "m")}
>>> map = cxc.pt_map(cxc.cart3d, cxc.sph3d)
>>> map(p)
{'r': Q(1., 'm'), 'theta': Q(1.57079633, 'rad'), 'phi': Q(0., 'rad')}

Coordinates without units are also accepted, interpreted having units of the unxt.AbstractUnitSystem, which must be passed.

>>> p = {"x": 1.0, "y": 0.0, "z": 0.0}
>>> map = cxc.pt_map(cxc.cart3d, cxc.sph3d, usys=u.unitsystems.si)
>>> map(p)
{'r': Array(1., dtype=float64, ...),
 'theta': Array(1.57079633, dtype=float64),
 'phi': Array(0., dtype=float64, ...)}

unxt.Quantity inputs are also accepted, and are interpreted as being in Cartesian coordinates.

>>> p = u.Q([1.0, 0.0, 0.0], "m")
>>> map = cxc.pt_map(cxc.cart3d, cxc.sph3d)
>>> map(p)
QMatrix([1.        , 1.57079633, 0.        ], '(m, rad, rad)')

Array-Like inputs are interpreted as Cartesian coordinates with units from the required unxt.AbstractUnitSystem.

>>> p = [1.0, 0.0, 0.0]
>>> map = cxc.pt_map(cxc.cart3d, cxc.sph3d, usys=u.unitsystems.si)
>>> map(p)
Array([1.        , 1.57079633, 0.        ], dtype=float64)

coordinax.charts.pt_map(x: Any, from_chart: AbstractChart, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → Any

Parameters:

args (Any)
kwargs (Any)

Return type:

Point transformation from chart to chart, using their manifolds.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {}
>>> cxc.pt_map(p, cxc.cart0d, cxc.cart0d)
{}

>>> p = {"r": u.Q(5.0, "m")}
>>> cxc.pt_map(p, cxc.radial1d, cxc.cart1d)
{'x': Q(5., 'm')}

>>> p = {"r": u.Q(5.0, "m"), "theta": u.Q(90, "deg")}
>>> cxc.pt_map(p, cxc.polar2d, cxc.cart2d)
{'x': Q(3.061617e-16, 'm'), 'y': Q(5., 'm')}

>>> p = {"r": u.Q(5.0, "m"), "theta": u.Q(90, "deg"), "phi": u.Q(0, "deg")}
>>> cxc.pt_map(p, cxc.sph3d, cxc.cart3d)
{'x': Q(5., 'm'), 'y': Q(0., 'm'), 'z': Q(3.061617e-16, 'm')}

coordinax.charts.pt_map(p: dict[str, Any], from_M: AbstractManifold, from_chart: AbstractChart, to_M: AbstractManifold, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

AbstractChart -> Cartesian -> AbstractChart.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {"r": u.Q(5.0, "m"), "theta": u.Q(90, "deg")}
>>> map = cxc.pt_map.invoke(dict[str, u.Q], cxm.Rn, cxc.AbstractChart,
...                         cxm.Rn, cxc.AbstractChart)
>>> map(p, cxm.R2, cxc.polar2d, cxm.R2, cxc.cart2d)
{'x': Q(3.061617e-16, 'm'), 'y': Q(5., 'm')}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: AbstractChart, to_M: EuclideanManifold, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Identity conversion for matching charts.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u
>>> import quaxed.numpy as jnp

>>> q = {}
>>> q2 = cxc.pt_map(q, cxm.R0, cxc.cart0d, cxm.R0, cxc.cart0d)
>>> q is q2
True

>>> q = {"r": u.Q(3.0, "m")}
>>> q2 = cxc.pt_map(q, cxm.R1, cxc.radial1d, cxm.R1, cxc.radial1d)
>>> q is q2
True

>>> q = {"x": u.Q(1.0, "m"), "y": u.Q(2.0, "m")}
>>> q2 = cxc.pt_map(q, cxm.R2, cxc.cart2d, cxm.R2, cxc.cart2d)
>>> q is q2
True

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Radial1D, to_M: EuclideanManifold, to_chart: Cart1D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Radial1D -> Cart1D.

The r coordinate is converted to the x coordinate of the 1D system.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> q = {"r": u.Q(5.0, "m")}
>>> cxc.pt_map(q, cxm.R1, cxc.radial1d, cxm.R1, cxc.cart1d)
{'x': Q(5., 'm')}

>>> q = {"r": 5.0}  # No units
>>> cxc.pt_map(q, cxm.R1, cxc.radial1d, cxm.R1, cxc.cart1d)
{'x': 5.0}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Cart1D, to_M: EuclideanManifold, to_chart: Radial1D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Cart1D -> Radial1D.

The x coordinate is converted to the r coordinate of the 1D system.

Assumptions:

Cart1D and Radial1D are

>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {"x": u.Q(5.0, "m")}
>>> cxc.pt_map(p, cxm.R1, cxc.cart1d, cxm.R1, cxc.radial1d)
{'r': Q(5., 'm')}

>>> p = {"x": 5.0}  # No units
>>> cxc.pt_map(p, cxm.R1, cxc.cart1d, cxm.R1, cxc.radial1d)
{'r': 5.0}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Polar2D, to_M: EuclideanManifold, to_chart: Cart2D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Polar2D -> Cart2D.

The r and theta coordinates are converted to the x and y coordinates of the 2D Cartesian system.

>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {"r": u.Q(5.0, "m"), "theta": u.Q(90, "deg")}
>>> cxc.pt_map(p, cxm.R2, cxc.polar2d, cxm.R2, cxc.cart2d)
{'x': Q(3.061617e-16, 'm'), 'y': Q(5., 'm')}

>>> p = {"r": 5, "theta": 90}  # No units
>>> usys = u.unitsystem("km", "deg")
>>> cxc.pt_map(p, cxm.R2, cxc.polar2d, cxm.R2, cxc.cart2d, usys=usys)
{'x': Array(3.061617e-16, dtype=float64, ...),
 'y': Array(5., dtype=float64, ...)}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Cart2D, to_M: EuclideanManifold, to_chart: Polar2D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Cart2D -> Polar2D.

The x and y coordinates are converted to the r and theta coordinates of the 2D polar system.

>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {"x": u.Q(3, "m"), "y": u.Q(4, "m")}
>>> cxc.pt_map(p, cxm.R2, cxc.cart2d, cxm.R2, cxc.polar2d)
{'r': Q(5., 'm'), 'theta': Q(0.92729522, 'rad')}

>>> p = {"x": 3, "y": 4}  # No units
>>> cxc.pt_map(p, cxm.R2, cxc.cart2d, cxm.R2, cxc.polar2d)
{'r': Array(5., dtype=float64, ...),
 'theta': Array(0.92729522, dtype=float64, ...)}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Cylindrical3D, to_M: EuclideanManifold, to_chart: Cart3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Cylindrical3D -> Cart3D.

>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {"rho": u.Q(1.0, "m"), "phi": u.Q(90, "deg"), "z": u.Q(2.0, "m")}
>>> cxc.pt_map(p, cxm.R3, cxc.cyl3d, cxm.R3, cxc.cart3d)
{'x': Q(6.123234e-17, 'm'), 'y': Q(1., 'm'), 'z': Q(2., 'm')}

>>> p = {"rho": 1.0, "phi": 90, "z": 2.0}  # No units
>>> usys = u.unitsystem("m", "deg")
>>> cxc.pt_map(p, cxm.R3, cxc.cyl3d, cxm.R3, cxc.cart3d, usys=usys)
{'x': Array(6.123234e-17, dtype=float64, ...), 'y': Array(1., dtype=float64, ...),
 'z': 2.0}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Spherical3D, to_M: EuclideanManifold, to_chart: Cart3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Spherical3D -> Cart3D.

>>> import coordinax.charts as cxc
>>> import unxt as u
>>> import quaxed.numpy as jnp

A point on the +z axis (theta=0):

>>> p = {"r": u.Q(1.0, "m"), "theta": u.Q(0, "deg"), "phi": u.Q(0, "deg")}
>>> cxc.pt_map(p, cxm.R3, cxc.sph3d, cxm.R3, cxc.cart3d)
{'x': Q(0., 'm'), 'y': Q(0., 'm'), 'z': Q(1., 'm')}

A point on the equator (theta=90 deg, phi=0):

>>> p = {"r": 2.0, "theta": 90, "phi": 0}
>>> usys = u.unitsystem("m", "deg")
>>> cxc.pt_map(p, cxm.R3, cxc.sph3d, cxm.R3, cxc.cart3d, usys=usys)
{'x': Array(2., dtype=float64, ...),
 'y': Array(0., dtype=float64, ...),
 'z': Array(1.2246468e-16, dtype=float64, ...)}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: LonLatSpherical3D, to_M: EuclideanManifold, to_chart: Cart3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

LonLatSpherical3D -> Cart3D.

>>> import coordinax.charts as cxc
>>> import unxt as u

A point at the north pole (lat=90 deg):

>>> p = {"lon": u.Q(0, "deg"), "lat": u.Q(90, "deg"), "distance": u.Q(1.0, "m")}
>>> cxc.pt_map(p, cxm.R3, cxc.lonlat_sph3d, cxm.R3, cxc.cart3d)
{'x': Q(6.123234e-17, 'm'), 'y': Q(0., 'm'), 'z': Q(1., 'm')}

A point on the equator at lon=0:

>>> p = {"lon": 0, "lat": 0, "distance": 2}
>>> cxc.pt_map(p, cxm.R3, cxc.lonlat_sph3d, cxm.R3, cxc.cart3d)
{'x': Array(2., dtype=float64, ...),
 'y': Array(0., dtype=float64, ...),
 'z': Array(0., dtype=float64, ...)}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: LonCosLatSpherical3D, to_M: EuclideanManifold, to_chart: Cart3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

LonCosLatSpherical3D -> Cart3D.

Components are (lon_coslat, lat, r), where lon_coslat := lon * cos(lat). Longitude is undefined at the poles (cos(lat) == 0); we set lon = 0 by convention there to avoid NaNs.

>>> import coordinax.charts as cxc
>>> import unxt as u

A point on the equator (lat=0, so lon_coslat = lon):

>>> p = {"lon_coslat": u.Q(0, "deg"), "lat": u.Q(0, "deg"),
...      "distance": u.Q(1.0, "m")}
>>> cxc.pt_map(p, cxm.R3, cxc.loncoslat_sph3d, cxm.R3, cxc.cart3d)
{'x': Q(1., 'm'), 'y': Q(0., 'm'), 'z': Q(0., 'm')}

At the north pole (lat=90), lon_coslat is effectively 0 regardless of lon:

>>> p = {"lon_coslat": u.Q(0, "deg"), "lat": u.Q(90, "deg"),
...      "distance": u.Q(2.0, "m")}
>>> cxc.pt_map(p, cxm.R3, cxc.loncoslat_sph3d, cxm.R3, cxc.cart3d)
{'x': Q(1.2246468e-16, 'm'), 'y': Q(0., 'm'), 'z': Q(2., 'm')}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: MathSpherical3D, to_M: EuclideanManifold, to_chart: Cart3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

MathSpherical3D -> Cart3D.

theta: azimuth in the x-y plane (longitude-like)
phi : polar angle from +z, with phi in [0, pi]

>>> import coordinax.charts as cxc
>>> import unxt as u

A point on the +z axis (phi=0):

>>> p = {"r": u.Q(1.0, "m"), "theta": u.Q(0, "deg"), "phi": u.Q(0, "deg")}
>>> cxc.pt_map(p, cxm.R3, cxc.math_sph3d, cxm.R3, cxc.cart3d)
{'x': Q(0., 'm'), 'y': Q(0., 'm'), 'z': Q(1., 'm')}

A point on the +x axis (theta=0, phi=90):

>>> p = {"r": u.Q(2.0, "m"), "theta": u.Q(0, "deg"), "phi": u.Q(90, "deg")}
>>> cxc.pt_map(p, cxm.R3, cxc.math_sph3d, cxm.R3, cxc.cart3d)
{'x': Q(2., 'm'), 'y': Q(0., 'm'), 'z': Q(1.2246468e-16, 'm')}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: ProlateSpheroidal3D, to_M: EuclideanManifold, to_chart: Cart3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

ProlateSpheroidal3D -> Cart3D.

We calculate through cylindrical coordinates first:

$rho = sqrt{(mu-Delta^2)left(1-frac{|\nu|}{Delta^2}right)}$ $z = sqrt{mu,frac{|\nu|}{Delta^2}};mathrm{sign}(nu)$ $phi = phi.$

Then convert to Cartesian:

$x=rhocosphi$, $y=rhosinphi$, $z=z$.

>>> import coordinax.charts as cxc
>>> import unxt as u
>>> import quaxed.numpy as jnp

>>> prolatesph3d = cxc.ProlateSpheroidal3D(Delta=u.StaticQuantity(2.0, "m"))

>>> p = {"mu": u.Q(5.0, "m2"), "nu": u.Q(1.0, "m2"), "phi": u.Q(0, "rad")}
>>> cxc.pt_map(p, cxm.R3, prolatesph3d, cxm.R3, cxc.cart3d)
{'x': Q(0.8660254, 'm'), 'y': Q(0., 'm'), 'z': Q(1.11803399, 'm')}

>>> p = {"mu": 5.0, "nu": 1.0, "phi": 0}  # No units
>>> usys = u.unitsystem("m", "rad")
>>> cxc.pt_map(p, cxm.R3, prolatesph3d, cxm.R3, cxc.cart3d, usys=usys)
{'x': Array(0.8660254, dtype=float64),
 'y': Array(0., dtype=float64),
 'z': Array(1.11803399, dtype=float64)}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Cart3D, to_M: EuclideanManifold, to_chart: Cylindrical3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Cart3D -> Cylindrical3D.

>>> import coordinax.main as cx
>>> import unxt as u

>>> p = {"x": u.Q(3.0, "m"), "y": u.Q(4.0, "m"), "z": u.Q(5.0, "m")}
>>> cxc.pt_map(p, cxm.R3, cxc.cart3d, cxm.R3, cxc.cyl3d)
{'rho': Q(5., 'm'), 'phi': Q(0.92729522, 'rad'), 'z': Q(5., 'm')}

>>> p = {"x": 3.0, "y": 4.0, "z": 5.0}  # No units
>>> cxc.pt_map(p, cxm.R3, cxc.cart3d, cxm.R3, cxc.cyl3d)
{'rho': Array(5., dtype=float64, ...),
 'phi': Array(0.92729522, dtype=float64, ...),
 'z': 5.0}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Cart3D | Cylindrical3D, to_M: EuclideanManifold, to_chart: AbstractSpherical3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Cart3D -> Spherical3D -> AbstractSpherical3D.

>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {"x": u.Q(0.0, "m"), "y": u.Q(0.0, "m"), "z": u.Q(1.0, "m")}
>>> cxc.pt_map(p, cxm.R3, cxc.cart3d, cxm.R3, cxc.loncoslat_sph3d)
{'lon_coslat': Q(0., 'rad'), 'lat': Q(90., 'deg'), 'distance': Q(1., 'm')}

>>> p = {"rho": 0, "phi": 180, "z": 1}
>>> usys = u.unitsystem("m", "deg")
>>> cxc.pt_map(p, cxm.R3, cxc.cyl3d, cxm.R3, cxc.loncoslat_sph3d, usys=usys)
{'lon_coslat': Array(1.10218212e-14, dtype=float64),
 'lat': Array(1.57079633, dtype=float64),
 'distance': Array(1., dtype=float64, weak_type=True)}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Cart3D, to_M: EuclideanManifold, to_chart: Spherical3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Cart3D -> Spherical3D.

>>> import coordinax.charts as cxc
>>> import unxt as u

A point on the +z axis:

>>> p = {"x": u.Q(0.0, "m"), "y": u.Q(0.0, "m"), "z": u.Q(1.0, "m")}
>>> cxc.pt_map(p, cxm.R3, cxc.cart3d, cxm.R3, cxc.sph3d)
{'r': Q(1., 'm'), 'theta': Q(0., 'rad'), 'phi': Q(0., 'rad')}

A point on the +x axis:

>>> p = {"x": 2.0, "y": 0.0, "z": 0.0}  # No units
>>> cxc.pt_map(p, cxm.R3, cxc.cart3d, cxm.R3, cxc.sph3d)
{'r': Array(2., dtype=float64, ...),
 'theta': Array(1.57079633, dtype=float64),
 'phi': Array(0., dtype=float64, ...)}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Cylindrical3D, to_M: EuclideanManifold, to_chart: Spherical3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Cylindrical3D -> Spherical3D.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

A point on the z-axis (rho=0):

>>> p = {"rho": u.Q(0.0, "m"), "phi": u.Q(0, "rad"), "z": u.Q(1.0, "m")}
>>> cxc.pt_map(p, cxm.R3, cxc.cyl3d, cxm.R3, cxc.sph3d)
{'r': Q(1., 'm'), 'theta': Q(0., 'rad'), 'phi': Q(0, 'rad')}

A point in the xy-plane (z=0):

>>> p = {"rho": 3.0, "phi": 0, "z": 0.0}  # No units
>>> cxc.pt_map(p, cxm.R3, cxc.cyl3d, cxm.R3, cxc.sph3d)
{'r': Array(3., dtype=float64, ...), 'theta': Array(1.57079633, dtype=float64),
 'phi': 0}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Spherical3D, to_M: EuclideanManifold, to_chart: Cylindrical3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Spherical3D -> Cylindrical3D.

>>> import coordinax.charts as cxc
>>> import coordinax.manifolds as cxm
>>> import unxt as u

A point on the +z axis (theta=0):

>>> p = {"r": u.Q(1.0, "m"), "theta": u.Q(0, "rad"), "phi": u.Q(0, "rad")}
>>> cxc.pt_map(p, cxm.R3, cxc.sph3d, cxm.R3, cxc.cyl3d)
{'rho': Q(0., 'm'), 'phi': Q(0, 'rad'), 'z': Q(1., 'm')}

A point on the equator (theta=90 deg):

>>> p = {"r": 2.0, "theta": 90, "phi": 0}  # No units
>>> usys = u.unitsystem("m", "deg")
>>> cxc.pt_map(p, cxm.R3, cxc.sph3d, cxm.R3, cxc.cyl3d, usys=usys)
{'rho': Array(2., dtype=float64, ...), 'phi': 0,
 'z': Array(1.2246468e-16, dtype=float64, ...)}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Spherical3D, to_M: EuclideanManifold, to_chart: LonLatSpherical3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Spherical3D -> LonLatSpherical3D.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

Spherical theta=0 corresponds to lat=90 (north pole):

>>> p = {"r": u.Q(1.0, "m"), "theta": u.Q(0, "rad"), "phi": u.Q(0, "rad")}
>>> cxc.pt_map(p, cxm.R3, cxc.sph3d, cxm.R3, cxc.lonlat_sph3d)
{'lon': Q(0, 'rad'), 'lat': Q(90., 'deg'), 'distance': Q(1., 'm')}

Spherical theta=90 deg corresponds to lat=0 (equator):

>>> p = {"r": 1.0, "theta": 0, "phi": 0}  # No units
>>> cxc.pt_map(p, cxm.R3, cxc.sph3d, cxm.R3, cxc.lonlat_sph3d)
{'lon': 0, 'lat': 1.5707963267948966, 'distance': 1.0}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Spherical3D, to_M: EuclideanManifold, to_chart: LonCosLatSpherical3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Spherical3D -> LonCosLatSpherical3D.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

On the equator (theta=90 deg), lon_coslat equals lon:

>>> p = {"r": u.Q(1.0, "m"), "theta": u.Q(90, "deg"), "phi": u.Q(45, "deg")}
>>> cxc.pt_map(p, cxm.R3, cxc.sph3d, cxm.R3, cxc.loncoslat_sph3d)
{'lon_coslat': Q(45., 'deg'), 'lat': Q(0., 'deg'), 'distance': Q(1., 'm')}

At the north pole (theta=0), lon_coslat = 0 regardless of phi:

>>> p = {"r": 1.0, "theta": 0, "phi": 45}  # No units
>>> usys = u.unitsystem("m", "deg")
>>> cxc.pt_map(p, cxm.R3, cxc.sph3d, cxm.R3, cxc.loncoslat_sph3d, usys=usys)
{'lon_coslat': Array(2.7554553e-15, dtype=float64, ...),
 'lat': 1.5707963267948966, 'distance': 1.0}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Spherical3D, to_M: EuclideanManifold, to_chart: MathSpherical3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Spherical3D -> MathSpherical3D.

Swaps theta and phi: Physics (theta=polar, phi=azimuth) to Math (theta=azimuth, phi=polar).

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {"r": u.Q(1.0, "m"), "theta": u.Q(30, "deg"), "phi": u.Q(60, "deg")}
>>> cxc.pt_map(p, cxm.R3, cxc.sph3d, cxm.R3, cxc.math_sph3d)
{'r': Q(1., 'm'), 'theta': Q(60, 'deg'), 'phi': Q(30, 'deg')}

>>> p = {"r": 1.0, "theta": 30, "phi": 60}  # No units
>>> usys = u.unitsystem("m", "deg")
>>> cxc.pt_map(p, cxm.R3, cxc.sph3d, cxm.R3, cxc.math_sph3d, usys=usys)
{'r': 1.0, 'theta': 60, 'phi': 30}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: MathSpherical3D, to_M: EuclideanManifold, to_chart: Spherical3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

MathSpherical3D -> Spherical3D.

Swaps theta and phi: Math (theta=azimuth, phi=polar) to Physics (theta=polar, phi=azimuth).

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {"r": u.Q(1.0, "m"), "theta": u.Q(60, "deg"), "phi": u.Q(30, "deg")}
>>> cxc.pt_map(p, cxm.R3, cxc.math_sph3d, cxm.R3, cxc.sph3d)
{'r': Q(1., 'm'), 'theta': Q(30, 'deg'), 'phi': Q(60, 'deg')}

>>> p = {"r": 1.0, "theta": 60, "phi": 30}  # No units
>>> usys = u.unitsystem("m", "deg")
>>> cxc.pt_map(p, cxm.R3, cxc.math_sph3d, cxm.R3, cxc.sph3d, usys=usys)
{'r': 1.0, 'theta': 30, 'phi': 60}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: ProlateSpheroidal3D, to_M: EuclideanManifold, to_chart: Cylindrical3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

ProlateSpheroidal3D -> Cylindrical3D.

Uses the focal length $Delta$ stored on from_chart.

Validity constraints (enforced by the representation) are:

$Delta > 0$,
$mu ge Delta^2$,
$|nu| le Delta^2$.

The conversion proceeds via

$rho = sqrt{(mu-Delta^2)left(1-frac{|\nu|}{Delta^2}right)}$, $z = sqrt{mu,frac{|\nu|}{Delta^2}},mathrm{sign}(nu)$, $phi = phi$.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> prolatesph3d = cxc.ProlateSpheroidal3D(Delta=u.StaticQuantity(2.0, "m"))

>>> p = {"mu": u.Q(5.0, "m2"), "nu": u.Q(1.0, "m2"), "phi": u.Q(0, "rad")}
>>> cxc.pt_map(p, cxm.R3, prolatesph3d, cxm.R3, cxc.cyl3d)
{'rho': Q(0.8660254, 'm'), 'phi': Q(0, 'rad'), 'z': Q(1.11803399, 'm')}

>>> p = {"mu": 5.0, "nu": 1.0, "phi": 0}  # No units
>>> usys = u.unitsystem("m", "rad")
>>> cxc.pt_map(p, cxm.R3, prolatesph3d, cxm.R3, cxc.cyl3d, usys=usys)
{'rho': Array(0.8660254, dtype=float64), 'phi': 0,
 'z': Array(1.11803399, dtype=float64)}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: Cylindrical3D, to_M: EuclideanManifold, to_chart: ProlateSpheroidal3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Cylindrical3D -> ProlateSpheroidal3D.

Uses the focal length $Delta$ stored on to_chart.

Let $R^2 = rho^2$ and $z^2 = z^2$ and define

$S = R^2 + z^2 + Delta^2$, $D_f = R^2 + z^2 - Delta^2$, $D = sqrt{D_f^2 + 4 R^2 Delta^2}$.

Then

$mu = Delta^2 + tfrac12(D + D_f)$ (with numerically-stable branches), $|nu| = dfrac{2Delta^2}{S + D},z^2$, and $nu = |\nu|,mathrm{sign}(z)$, with a stability fix when $Delta^2 - |nu|$ is small.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> prolatesph3d = cxc.ProlateSpheroidal3D(Delta=u.StaticQuantity(2.0, "m"))

A point on the z-axis (rho=0):

>>> p = {"rho": u.Q(0.0, "m"), "phi": u.Q(0, "rad"), "z": u.Q(3.0, "m")}
>>> cxc.pt_map(p, cxm.R3, cxc.cyl3d, cxm.R3, prolatesph3d)
{'mu': Q(9., 'm2'), 'nu': Q(4., 'm2'), 'phi': Q(0, 'rad')}

A point in the xy-plane (z=0):

>>> p = {"rho": u.Q(2.0, "m"), "phi": u.Q(0, "rad"), "z": u.Q(0.0, "m")}
>>> cxc.pt_map(p, cxm.R3, cxc.cyl3d, cxm.R3, prolatesph3d)
{'mu': Q(8., 'm2'), 'nu': Q(0., 'm2'), 'phi': Q(0, 'rad')}

Without units:

>>> p = {"rho": 2.0, "phi": 0, "z": 3.0}  # No units
>>> usys = u.unitsystem("m", "rad")
>>> cxc.pt_map(p, cxm.R3, cxc.cyl3d, cxm.R3, prolatesph3d, usys=usys)
{'mu': Array(14.52079729, dtype=float64),
 'nu': Array(2.47920271, dtype=float64), 'phi': 0}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: ProlateSpheroidal3D, to_M: EuclideanManifold, to_chart: ProlateSpheroidal3D, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

{class}`coordinax.charts.ProlateSpheroidal3D` -> itself.

If the focal length is unchanged (to_chart.Delta == from_chart.Delta), this is the identity map.

If the focal length changes, we convert via cylindrical coordinates:

Prolate(Delta_in) -> Cylindrical -> Prolate(Delta_out).

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

Same focal length (identity transformation):

>>> prolate = cxc.ProlateSpheroidal3D(Delta=u.StaticQuantity(2.0, "m"))
>>> p = {"mu": u.Q(5.0, "m2"), "nu": u.Q(1.0, "m2"), "phi": u.Q(0, "rad")}
>>> cxc.pt_map(p, cxm.R3, prolate, cxm.R3, prolate)
{'mu': Q(5., 'm2'),
 'nu': Q(1., 'm2'),
 'phi': Q(0., 'rad')}

Different focal lengths (converts via cylindrical):

>>> prolate_in = cxc.ProlateSpheroidal3D(Delta=u.StaticQuantity(2.0, "m"))
>>> prolate_out = cxc.ProlateSpheroidal3D(Delta=u.StaticQuantity(3.0, "m"))
>>> p = {"mu": u.Q(5.0, "m2"), "nu": u.Q(1.0, "m2"), "phi": u.Q(0, "rad")}
>>> cxc.pt_map(p, cxm.R3, prolate_in, cxm.R3, prolate_out)
{'mu': Q(9.85889894, 'm2'),
 'nu': Q(1.14110106, 'm2'),
 'phi': Q(0., 'rad')}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: CartND, to_M: EuclideanManifold, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

CartND -> AbstractChart.

Converts from N-dimensional Cartesian (with a single ‘q’ array) to any other chart type by first extracting the appropriate fixed-dimensional Cartesian representation.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

Convert 3D CartND to Spherical:

>>> p = {"q": u.Q([1.0, 0.0, 0.0], "m")}
>>> cxc.pt_map(p, cxm.RN, cxc.cartnd, cxm.R3, cxc.sph3d)
{'r': Q(1., 'm'), 'theta': Q(1.57079633, 'rad'), 'phi': Q(0., 'rad')}

Convert 2D CartND to Polar:

>>> p = {"q": u.Q([3.0, 4.0], "m")}
>>> cxc.pt_map(p, cxm.RN, cxc.cartnd, cxm.R2, cxc.polar2d)
{'r': Q(5., 'm'), 'theta': Q(0.92729522, 'rad')}

Convert 1D CartND to Radial:

>>> p = {"q": u.Q([5.0], "m")}
>>> cxc.pt_map(p, cxm.RN, cxc.cartnd, cxm.R1, cxc.radial1d)
{'r': Q(5., 'm')}

Convert CartND to Cart3D:

>>> p = {"q": u.Q([1.0, 2.0, 3.0], "m")}
>>> cxc.pt_map(p, cxm.RN, cxc.cartnd, cxm.R3, cxc.cart3d)
{'x': Q(1., 'm'), 'y': Q(2., 'm'), 'z': Q(3., 'm')}

coordinax.charts.pt_map(p: dict[str, Any], from_M: EuclideanManifold, from_chart: AbstractChart, to_M: EuclideanManifold, to_chart: CartND, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

AbstractChart -> CartND.

Converts from any chart type to N-dimensional Cartesian (with a single ‘q’ array) by first transforming to the appropriate fixed-dimensional Cartesian representation.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

Convert Cart3D to CartND:

>>> p = {"x": u.Q(1.0, "m"), "y": u.Q(2.0, "m"), "z": u.Q(3.0, "m")}
>>> cxc.pt_map(p, cxm.R3, cxc.cart3d, cxm.R3, cxc.cartnd)
{'q': Q([1., 2., 3.], 'm')}

Convert Cart2D to CartND:

>>> p = {"x": u.Q(3.0, "m"), "y": u.Q(4.0, "m")}
>>> cxc.pt_map(p, cxm.R2, cxc.cart2d, cxm.R2, cxc.cartnd)
{'q': Q([3., 4.], 'm')}

Convert Radial to CartND:

>>> p = {"r": u.Q(3.0, "m")}
>>> cxc.pt_map(p, cxc.radial1d, cxc.cartnd)
{'q': Q([3.], 'm')}

Convert Cylindrical to CartND (z-axis point):

>>> p = {"rho": u.Q(0.0, "m"), "phi": u.Q(0, "rad"), "z": u.Q(5.0, "m")}
>>> cxc.pt_map(p, cxc.cyl3d, cxc.cartnd)
{'q': Q([0., 0., 5.], 'm')}

coordinax.charts.pt_map(q: AbstractQuantity, from_M: EuclideanManifold, from_chart: AbstractChart, to_M: EuclideanManifold, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → AbstractQuantity

Parameters:

args (Any)
kwargs (Any)

Return type:

Identity point transform for Quantity inputs on uniform-unit charts.

For charts where all components share the same unit (Cartesian charts, 0D/1D charts), a Quantity can be passed directly and is returned unchanged when the source and target charts are the same type.

This dispatch only handles identity transformations (same chart type). For transformations between different chart types with Quantity input, the Quantity must first be converted to a coordinate dictionary.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

1D Cartesian (identity):

>>> q = u.Q([5.0], "m")
>>> cxc.pt_map(q, cxm.R1, cxc.cart1d, cxm.R1, cxc.cart1d, usys=None) is q
True

2D Cartesian (identity):

>>> q = u.Q([3.0, 4.0], "m")
>>> cxc.pt_map(q, cxm.R2, cxc.cart2d, cxm.R2, cxc.cart2d, usys=None) is q
True

3D Cartesian (identity):

>>> q = u.Q([1.0, 2.0, 3.0], "km")
>>> cxc.pt_map(q, cxm.R3, cxc.cart3d, cxm.R3, cxc.cart3d, usys=None) is q
True

N-D Cartesian (identity):

>>> q = u.Q([1.0, 2.0, 3.0, 4.0], "m")
>>> cxc.pt_map(q, cxm.RN, cxc.cartnd, cxm.RN, cxc.cartnd, usys=None) is q
True

coordinax.charts.pt_map(p: AbstractQuantity, from_M: EuclideanManifold, from_chart: AbstractChart, to_M: EuclideanManifold, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → QMatrix

Parameters:

args (Any)
kwargs (Any)

Return type:

Transform a QMatrix between charts.

Converts the components of a QMatrix from one chart to another, preserving the matrix structure with potentially different units per component.

>>> import coordinax.charts as cxc
>>> import unxt as u

2D Cartesian to Polar:

>>> q = u.Q([3.0, 4.0], "m")
>>> result = cxc.pt_map(q, cxc.cart2d, cxc.polar2d)
>>> result.shape
(2,)
>>> result.unit
UnitsMatrix("(m, rad)")

3D Cartesian to Spherical:

>>> q = u.Q([1.0, 0.0, 0.0], "kpc")
>>> result = cxc.pt_map(q, cxc.cart3d, cxc.sph3d)
>>> result.shape
(3,)

Batched transformation:

>>> q_batch = u.Q([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]], "m")
>>> result = cxc.pt_map(q_batch, cxc.cart3d, cxc.sph3d)
>>> result.shape
(2, 3)

coordinax.charts.pt_map(p: Array | list, from_M: EuclideanManifold, from_chart: AbstractChart, to_M: EuclideanManifold, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None) → Array

Parameters:

args (Any)
kwargs (Any)

Return type:

Point transform for array input.

Transforms a point represented as a raw array (without units) from one chart to another. The unit system usys provides the units for interpreting the array components.

Return type:

dict[str, Any]

Returns:

Array – Array of shape (..., ndim) containing the transformed coordinates in to_chart.
>>> import coordinax.charts as cxc
>>> import unxt as u
>>> import jax.numpy as jnp
**Cartesian to Spherical (3D) (****)
>>> usys = u.unitsystem(“m”, “rad”)
>>> p = jnp.array([1.0, 0.0, 0.0]) # Point on x-axis
>>> cxc.pt_map(p, cxc.cart3d, cxc.sph3d, usys=usys)
Array([1. , 1.57079633, 0. ], dtype=float64)
The result is [r, theta, phi] = [1, pi/2, 0] (on equator, x-axis).
**Spherical to Cartesian (3D) (****)
>>> p = jnp.array([2.0, jnp.pi/4, 0.0]) # r=2, theta=45°, phi=0
>>> cxc.pt_map(p, cxc.sph3d, cxc.cart3d, usys=usys)
Array([1.41421356, 0. , 1.41421356], dtype=float64)
**Cartesian to Cylindrical (****)
>>> p = jnp.array([3.0, 4.0, 5.0])
>>> cxc.pt_map(p, cxc.cart3d, cxc.cyl3d, usys=usys)
Array([5. , 0.92729522, 5. ], dtype=float64)
The result is [rho, phi, z] = [5, arctan(4/3), 5].
**Batched transformation (****)
>>> p_batch = jnp.array([[1.0, 0.0, 0.0],
… [0.0, 1.0, 0.0],
… [0.0, 0.0, 1.0]])
>>> cxc.pt_map(p_batch, cxc.cart3d, cxc.sph3d, usys=usys)
Array([[1. , 1.57079633, 0. ], – [1. , 1.57079633, 1.57079633], [1. , 0. , 0. ]], dtype=float64)
**2D Cartesian to Polar (****)
>>> usys_2d = u.unitsystem(“m”, “rad”)
>>> p = jnp.array([3.0, 4.0])
>>> cxc.pt_map(p, cxc.cart2d, cxc.polar2d, usys=usys_2d)
Array([5. , 0.92729522], dtype=float64)
.. py (function:: pt_map(p: dict[str, typing.Any], from_M: coordinax._src.product.manifold.CartesianProductManifold, from_chart: coordinax._src.product.chart.AbstractCartesianProductChart, to_M: coordinax._src.product.manifold.CartesianProductManifold, to_chart: coordinax._src.product.chart.AbstractCartesianProductChart, /, *, usys: unxt._src.unitsystems.base.AbstractUnitSystem | None = None) -> dict[str, typing.Any]) – :noindex:
ABC CartesianProductChart -> CartesianProductChart (factorwise).
Transforms between product charts by applying coordinax.charts.pt_map to
each factor independently. Requires compatible factor structure (same number
of factors, pairwise compatible).
Mathematical definition
$$ varphi left(prod_i S_i,;prod_i R_i,;pright) – = bigl(varphi(S_i,,R_i,,p_i)bigr)_i $$
where $varphi$ denotes {func}`~coordinax.charts.pt_map` and
$p_i$ are the factor dictionaries split from $p$.

Parameters:

args (Any)
kwargs (Any)

Examples

>>> import coordinax.charts as cxc
>>> import unxt as u

Transform a Cartesian product chart between spatial representations:

>>> prod_crt = cxc.CartesianProductChart((cxc.time1d, cxc.cart3d), ("t", "q"))
>>> prod_sph = cxc.CartesianProductChart((cxc.time1d, cxc.sph3d), ("t", "q"))
>>> p = {"t.t": u.Q(1.0, "s"), "q.x": u.Q(1.0, "m"), "q.y": u.Q(0.0, "m"),
...      "q.z": u.Q(0.0, "m")}
>>> result = cxc.pt_map(p, prod_crt, prod_sph)
>>> result["t.t"]
Q(1., 's')
>>> result["q.r"]
Q(1., 'm')

coordinax.charts.pt_map(p: dict[str, Any], from_M: AbstractManifold, from_chart: AbstractChart, to_M: CartesianProductManifold, to_chart: AbstractCartesianProductChart, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

AbstractChart -> Cartesian -> AbstractCartesianProductChart.

>>> import coordinax.charts as cxc
>>> import unxt as u

>>> chart = cxc.CartesianProductChart((cxc.sph2, cxc.cart1d), ("S2", "R1"))
>>> map = cxc.pt_map.invoke(dict[str, u.Q], cxc.Cart3D, cxc.CartesianProductChart)
>>> try: map({}, cxc.cart3d, chart)
... except NotImplementedError as e: print(e)
No general transform between Cart3D and CartesianProductChart.
Define explicit rules for non-product to product conversions.

coordinax.charts.pt_map(p: dict[str, Any], from_M: CartesianProductManifold, from_chart: AbstractCartesianProductChart, to_M: AbstractManifold, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

AbstractCartesianProductChart -> Cartesian -> AbstractChart.

>>> import coordinax.charts as cxc
>>> import unxt as u

>>> chart = cxc.CartesianProductChart((cxc.sph2, cxc.cart1d), ("S2", "R1"))
>>> map = cxc.pt_map.invoke(dict[str, u.Q], cxc.CartesianProductChart, cxc.Cart3D)
>>> try: map({}, chart, cxc.cart3d)
... except NotImplementedError as e: print(e)
No general transform between CartesianProductChart and Cart3D.
Define explicit rules for product to non-product conversions.

coordinax.charts.pt_map(p: dict[str, Any], from_chart: EmbeddedChart, to_chart: EmbeddedChart, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Convert between embedded manifolds with a shared ambient space.

This function transforms intrinsic coordinates from one embedded manifold to another by: 1. Embedding the point into the ambient space of the source manifold 2. Transforming in the ambient space (if the ambient charts differ) 3. Projecting back to the intrinsic coordinates of the target manifold

>>> import coordinax.charts as cxc
>>> import coordinax.manifolds as cxm
>>> import unxt as u
>>> import quaxed.numpy as jnp

Example 1: Two spheres with different radii

Both spheres use the same intrinsic SphericalTwoSphere chart but have different radii:

>>> sphere1 = cxm.EmbeddedChart(cxm.TwoSphereIn3D(radius=u.Q(1.0, "km")))
>>> sphere2 = cxm.EmbeddedChart(cxm.TwoSphereIn3D(radius=u.Q(2.0, "km")))

A point on sphere1 (theta=pi/4, phi=0):

>>> p = {"theta": u.Q(45, "deg"), "phi": u.Q(0, "deg")}
>>> p2 = cxc.pt_map(p, sphere1, sphere2)
>>> {k: v.uconvert("deg") for k, v in p2.items()}
{'theta': Q(45, 'deg'), 'phi': Q(0, 'deg')}

The angular coordinates are preserved (both spheres share the same angular parameterization via projection through the shared ambient space).

coordinax.charts.pt_map(p: dict[str, Any], from_chart: AbstractChart, to_chart: EmbeddedChart, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Project an ambient position into an embedded chart.

This transforms coordinates from an ambient chart (e.g., Cartesian or Spherical) into the intrinsic coordinates of an embedded manifold.

>>> import coordinax.charts as cxc
>>> import coordinax.manifolds as cxm
>>> import unxt as u
>>> import quaxed.numpy as jnp

From Cartesian ambient to SphericalTwoSphere intrinsic:

>>> sphere = cxm.EmbeddedChart(cxm.TwoSphereIn3D(radius=u.Q(1.0, "m")))

A point on the unit sphere in Cartesian coords (on equator, x-axis):

>>> p_cart = {"x": u.Q(1.0, "m"), "y": u.Q(0.0, "m"), "z": u.Q(0.0, "m")}
>>> cxc.pt_map(p_cart, cxc.cart3d, sphere)
{'theta': Q(1.57079633, 'rad'), 'phi': Q(0., 'rad')}

From Spherical ambient to SphericalTwoSphere intrinsic:

The ambient spherical coords (r, theta, phi) project to intrinsic (theta, phi), discarding the radial component:

>>> p_sph = {"r": 5, "theta": 1, "phi": 0.5}  # No units
>>> usys = u.unitsystem("m", "rad")
>>> cxc.pt_map(p_sph, cxc.sph3d, sphere, usys=usys)
{'theta': 1, 'phi': 0.5}

coordinax.charts.pt_map(p: dict[str, Any], from_chart: EmbeddedChart, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Embed intrinsic coordinates into an ambient representation.

This transforms intrinsic coordinates of an embedded manifold into coordinates of an ambient chart, which may differ from the embedding’s native ambient chart.

>>> import coordinax.charts as cxc
>>> import coordinax.manifolds as cxm
>>> import unxt as u
>>> import quaxed.numpy as jnp

From SphericalTwoSphere intrinsic to Cartesian ambient:

>>> sphere = cxm.EmbeddedChart(cxm.TwoSphereIn3D(radius=u.Q(1.0, "m")))

A point on the unit sphere (on equator, x-axis):

>>> p_sph = {"theta": u.Q(1.0, "rad"), "phi": u.Q(0.0, "rad")}
>>> cxc.pt_map(p_sph, sphere, cxc.cart3d)
{'x': Q(0.84147098, 'm'), 'y': Q(0., 'm'), 'z': Q(0.54030231, 'm')}

From SphericalTwoSphere intrinsic to Spherical ambient:

>>> p_sph = {"theta": u.Q(1.0, "rad"), "phi": u.Q(0.5, "rad")}
>>> cxc.pt_map(p_sph, sphere, cxc.sph3d)
{'r': Q(1., 'm'), 'theta': Q(1., 'rad'), 'phi': Q(0.5, 'rad')}

coordinax.charts.pt_map(p: dict[str, Any], M: EmbeddedManifold, from_chart: AbstractChart, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Convert between embedded manifolds with a shared ambient space.

>>> import unxt as u
>>> import coordinax.charts as cxc
>>> import coordinax.manifolds as cxm

>>> M = cxm.embedded_twosphere(radius=u.Q(1, "kpc"))
>>> M
EmbeddedManifold(intrinsic=HyperSphericalManifold(...),
                 ambient=Rn(3),
                 embed_map=TwoSphereIn3D(radius=Q(1, 'kpc')))
>>> x_cart = {"x": u.Q(1, "m"), "y": u.Q(2, "m"), "z": u.Q(3, "m")}

>>> x_sph2 = cxc.pt_map(x_cart, M, cxc.cart3d, cxc.loncoslat_sph2)
>>> x_sph2
{'lon_coslat': Q(0.66164791, 'rad'), 'lat': Q(53.3007748, 'deg')}

>>> cxc.pt_map(x_sph2, M, cxc.loncoslat_sph2, cxc.cart3d)
{'x': Q(0.26726124, 'kpc'), 'y': Q(0.53452248, 'kpc'),
 'z': Q(0.80178373, 'kpc')}

coordinax.charts.pt_map(p: Any, from_chart: Abstract3D, to_chart: AbstractSphericalTwoSphere, /, *, usys: AbstractUnitSystem | None = None) → Any

Parameters:

args (Any)
kwargs (Any)

Return type:

Project a point from the ambient chart to the two-sphere intrinsic chart.

This realization map is a special case for projecting from 3D charts to the two-sphere intrinsic chart, which is a common use case. The projection does not depend on the radius of the embedding, so this projection works in general.

>>> import unxt as u
>>> import coordinax.charts as cxc

>>> q = {"x": u.Q(1.0, "km"), "y": u.Q(0.0, "km"), "z": u.Q(0.0, "km")}
>>> cxc.pt_map(q, cxc.cart3d, cxc.sph2)
{'theta': Q(1.57079633, 'rad'), 'phi': Q(0., 'rad')}

coordinax.charts.pt_map(p: dict[str, Any], from_M: HyperSphericalManifold, from_chart: AbstractChart, to_M: HyperSphericalManifold, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

Identity conversion for matching charts.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> q = {"theta": u.Q(30, "deg"), "phi": u.Q(60, "deg")}
>>> cxc.pt_map(q, cxc.sph2, cxc.sph2) is q
True

>>> q = {"lon": u.Q(45, "deg"), "lat": u.Q(10, "deg")}
>>> cxc.pt_map(q, cxc.lonlat_sph2, cxc.lonlat_sph2) is q
True

>>> q = {"lon_coslat": u.Q(30, "deg"), "lat": u.Q(20, "deg")}
>>> cxc.pt_map(q, cxc.loncoslat_sph2, cxc.loncoslat_sph2) is q
True

>>> q = {"theta": u.Q(60, "deg"), "phi": u.Q(30, "deg")}
>>> cxc.pt_map(q, cxc.math_sph2, cxc.math_sph2) is q
True

coordinax.charts.pt_map(p: dict[str, Any], from_M: HyperSphericalManifold, from_chart: SphericalTwoSphere, to_M: HyperSphericalManifold, to_chart: LonLatSphericalTwoSphere, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

SphericalTwoSphere -> LonLatSphericalTwoSphere.

lat = pi/2 - theta, lon = phi.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {"theta": u.Q(0, "rad"), "phi": u.Q(0, "rad")}  # North pole
>>> cxc.pt_map(p, cxm.S2, cxc.sph2, cxm.S2, cxc.lonlat_sph2)
{'lon': Q(0, 'rad'), 'lat': Q(90., 'deg')}

>>> p = {"theta": u.Q(90, "deg"), "phi": u.Q(45, "deg")}  # Equator
>>> cxc.pt_map(p, cxm.S2, cxc.sph2, cxm.S2, cxc.lonlat_sph2)
{'lon': Q(45, 'deg'), 'lat': Q(0, 'deg')}

coordinax.charts.pt_map(p: dict[str, Any], from_M: HyperSphericalManifold, from_chart: LonLatSphericalTwoSphere, to_M: HyperSphericalManifold, to_chart: SphericalTwoSphere, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

LonLatSphericalTwoSphere -> SphericalTwoSphere.

theta = pi/2 - lat, phi = lon.

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {"lon": u.Q(45, "deg"), "lat": u.Q(0, "deg")}
>>> cxc.pt_map(p, cxm.S2, cxc.lonlat_sph2, cxm.S2, cxc.sph2)
{'theta': Q(90, 'deg'), 'phi': Q(45, 'deg')}

coordinax.charts.pt_map(p: dict[str, Any], from_M: HyperSphericalManifold, from_chart: SphericalTwoSphere, to_M: HyperSphericalManifold, to_chart: LonCosLatSphericalTwoSphere, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

SphericalTwoSphere -> LonCosLatSphericalTwoSphere.

lat = pi/2 - theta, lon_coslat = phi * cos(lat).

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u
>>> import quaxed.numpy as jnp

>>> p = {"theta": u.Q(90, "deg"), "phi": u.Q(45, "deg")}  # equator
>>> cxc.pt_map(p, cxm.S2, cxc.sph2, cxm.S2, cxc.loncoslat_sph2)
{'lon_coslat': Q(45., 'deg'), 'lat': Q(0., 'deg')}

>>> p = {"theta": u.Q(0, "deg"), "phi": u.Q(45, "deg")}  # north pole
>>> result = cxc.pt_map(p, cxm.S2, cxc.sph2, cxm.S2, cxc.loncoslat_sph2)
>>> bool(jnp.allclose(u.ustrip("deg", result["lat"]), 90.0))
True

coordinax.charts.pt_map(p: dict[str, Any], from_M: HyperSphericalManifold, from_chart: LonCosLatSphericalTwoSphere, to_M: HyperSphericalManifold, to_chart: SphericalTwoSphere, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

LonCosLatSphericalTwoSphere -> SphericalTwoSphere.

theta = pi/2 - lat, phi = lon_coslat / cos(lat).

>>> import coordinax.charts as cxc
>>> import coordinax.manifolds as cxm
>>> import unxt as u

>>> p = {"lon_coslat": u.Q(45, "deg"), "lat": u.Q(0, "deg")}
>>> cxc.pt_map(p, cxm.S2, cxc.loncoslat_sph2, cxm.S2, cxc.sph2)
{'theta': Q(90., 'deg'), 'phi': Q(45., 'deg')}

coordinax.charts.pt_map(p: dict[str, Any], from_M: HyperSphericalManifold, from_chart: SphericalTwoSphere, to_M: HyperSphericalManifold, to_chart: MathSphericalTwoSphere, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

SphericalTwoSphere -> MathSphericalTwoSphere.

Swaps theta and phi (physics -> math convention).

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {"theta": u.Q(30, "deg"), "phi": u.Q(60, "deg")}
>>> cxc.pt_map(p, cxm.S2, cxc.sph2, cxm.S2, cxc.math_sph2)
{'theta': Q(60, 'deg'), 'phi': Q(30, 'deg')}

coordinax.charts.pt_map(p: dict[str, Any], from_M: HyperSphericalManifold, from_chart: MathSphericalTwoSphere, to_M: HyperSphericalManifold, to_chart: SphericalTwoSphere, /, *, usys: AbstractUnitSystem | None = None) → dict[str, Any]

Parameters:

args (Any)
kwargs (Any)

Return type:

MathSphericalTwoSphere -> SphericalTwoSphere.

Swaps theta and phi (math -> physics convention).

>>> import coordinax.manifolds as cxm
>>> import coordinax.charts as cxc
>>> import unxt as u

>>> p = {"theta": u.Q(60, "deg"), "phi": u.Q(30, "deg")}
>>> cxc.pt_map(p, cxm.S2, cxc.math_sph2, cxm.S2, cxc.sph2)
{'theta': Q(30, 'deg'), 'phi': Q(60, 'deg')}

coordinax.charts.pt_map(x: Any, from_chart: AbstractChart, from_rep: Representation, to_chart: AbstractChart, to_rep: Representation, /, usys: AbstractUnitSystem | None = None) → Any

Parameters:

args (Any)
kwargs (Any)

Return type:

Convert point data between charts.

Convert a point from Cartesian coordinates to spherical coordinates:

>>> import coordinax.representations as cxr
>>> import coordinax.charts as cxc

Define a point in Cartesian coordinates:

>>> p = {"x": 1.0, "y": 2.0, "z": 3.0}

Convert it to spherical coordinates:

>>> q = cxc.pt_map(p, cxc.cart3d, cxr.point, cxc.sph3d, cxr.point)
>>> q
{'r': Array(3.74165739, dtype=float64, ...),
 'theta': Array(0.64052231, dtype=float64),
 'phi': Array(1.10714872, dtype=float64, ...)}

The output q represents the same geometric point but expressed in the target chart.

The representation remains unchanged; only the chart changes:

>>> cxc.pt_map(q, cxc.sph3d, cxr.point, cxc.cart3d, cxr.point)
{'x': Array(1., dtype=float64), 'y': Array(2., dtype=float64),
 'z': Array(3., dtype=float64)}

Let’s work through more examples.

Cartesian to Spherical (with units):

>>> import unxt as u
>>> p = {"x": u.Q(1.0, "m"), "y": u.Q(0.0, "m"), "z": u.Q(0.0, "m")}
>>> cxc.pt_map(p, cxc.cart3d, cxr.point, cxc.sph3d, cxr.point)
{'r': Q(1., 'm'), 'theta': Q(1.57079633, 'rad'), 'phi': Q(0., 'rad')}

Cylindrical to Cartesian (without units):

>>> p = {"rho": 3.0, "phi": 0, "z": 4.0}
>>> cxc.pt_map(p, cxc.cyl3d, cxr.point, cxc.cart3d, cxr.point)
{'x': Array(3., dtype=float64, ...), 'y': Array(0., dtype=float64, ...),
 'z': 4.0}

Polar to Cartesian (2D):

>>> p = {"r": u.Q(5.0, "m"), "theta": u.Q(90, "deg")}
>>> cxc.pt_map(p, cxc.polar2d, cxr.point, cxc.cart2d, cxr.point)
{'x': Q(3.061617e-16, 'm'), 'y': Q(5., 'm')}

Between Spherical variants (Spherical to LonLatSpherical):

>>> p = {"r": u.Q(1.0, "m"), "theta": u.Q(45, "deg"), "phi": u.Q(0, "deg")}
>>> cxc.pt_map(p, cxc.sph3d, cxr.point, cxc.lonlat_sph3d, cxr.point)
{'lon': Q(0, 'deg'), 'lat': Q(45., 'deg'), 'distance': Q(1., 'm')}

Identity conversion (same chart):

>>> p = {"x": u.Q(2.0, "m"), "y": u.Q(3.0, "m")}
>>> cxc.pt_map(p, cxc.cart2d, cxr.point, cxc.cart2d, cxr.point) is p
True

coordinax.charts.pt_map(x: Any, from_chart: AbstractChart, from_rep: Representation, to_chart: AbstractChart, /, usys: AbstractUnitSystem | None = None) → Any

Parameters:

args (Any)
kwargs (Any)

Return type:

Convert point data between charts.

Convert a point from Cartesian coordinates to spherical coordinates:

>>> import coordinax.representations as cxr
>>> import coordinax.charts as cxc

Define a point in Cartesian coordinates:

>>> p = {"x": 1.0, "y": 2.0, "z": 3.0}

Convert it to spherical coordinates:

>>> q = cxc.pt_map(p, cxc.cart3d, cxr.point, cxc.sph3d)
>>> q
{'r': Array(3.74165739, dtype=float64, ...),
 'theta': Array(0.64052231, dtype=float64),
 'phi': Array(1.10714872, dtype=float64, ...)}

The output q represents the same geometric point but expressed in the target chart.

The representation remains unchanged; only the chart changes:

>>> cxc.pt_map(q, cxc.sph3d, cxr.point, cxc.cart3d)
{'x': Array(1., dtype=float64), 'y': Array(2., dtype=float64),
 'z': Array(3., dtype=float64)}

coordinax.charts.pt_map(x: Any, from_chart: AbstractChart, from_geom: PointGeometry, from_rep: Representation, to_chart: AbstractChart, to_geom: PointGeometry, to_rep: Representation, /, usys: AbstractUnitSystem | None = None) → Any

Parameters:

args (Any)
kwargs (Any)

Return type:

Convert point data between charts.

Convert a point from Cartesian coordinates to spherical coordinates:

>>> import coordinax.representations as cxr
>>> import coordinax.charts as cxc

Define a point in Cartesian coordinates:

>>> p = {"x": 1.0, "y": 2.0, "z": 3.0}

Convert it to spherical coordinates:

>>> cxc.pt_map(p, cxc.cart3d, cxr.point_geom, cxr.point,
...                             cxc.sph3d, cxr.point_geom, cxr.point)
{'r': Array(3.74165739, dtype=float64, ...),
 'theta': Array(0.64052231, dtype=float64),
 'phi': Array(1.10714872, dtype=float64, ...)}

coordinax.charts.pt_map(from_vec: coordinax.vectors._src.point.Point, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → coordinax.vectors._src.point.Point

Parameters:

args (Any)
kwargs (Any)

Return type:

Convert a point from one chart to another.

>>> import unxt as u
>>> import coordinax.main as cx
>>> import coordinax.charts as cxc

>>> vec = cx.Point.from_([1, 1, 1], "m")
>>> print(vec)
<Point: chart=Cart3D (x, y, z) [m]
    [1 1 1]>

>>> sph_vec = cxc.pt_map(vec, cx.sph3d)
>>> print(sph_vec)
<Point: chart=Spherical3D (r[m], theta[rad], phi[rad])
    [1.732 0.955 0.785]>

coordinax.charts.pt_map(from_vec: coordinax.vectors._src.point.Point, from_chart: AbstractChart, to_chart: AbstractChart, /, *, usys: AbstractUnitSystem | None = None) → coordinax.vectors._src.point.Point

Parameters:

args (Any)
kwargs (Any)

Return type:

Convert a vector from one chart to another.

>>> import unxt as u
>>> import coordinax.main as cx
>>> import coordinax.charts as cxc

>>> vec = cx.Point.from_([1, 1, 1], "m")
>>> sph_vec = cxc.pt_map(vec, cxc.cart3d, cx.sph3d)
>>> print(sph_vec)
<Point: chart=Spherical3D (r[m], theta[rad], phi[rad])
    [1.732 0.955 0.785]>

Parameters:

args (Any)
kwargs (Any)

Return type:

class coordinax.charts.Abstract0D#

Marker flag for 0D representations.

A 0D representation has no coordinate component.

class coordinax.charts.Cart0D(*, M: MT = Rn(0))#

Bases: AbstractFixedComponentsChart[MT, tuple[()], tuple[()]], Abstract0D

Zero-dimensional Cartesian chart.

This chart has no coordinate components and no coordinate dimensions. It is the canonical Cartesian chart for 0D representations.

>>> import coordinax.charts as cxc
>>> cxc.cart0d.components
()
>>> cxc.cart0d.coord_dimensions
()
>>> isinstance(cxc.cartesian_chart(cxc.cart0d), cxc.Cart0D)
True

Parameters:: M (TypeVar(MT, bound= AbstractManifold))

M: MT = Rn(0)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

property cartesian: Self#

Return the canonical Cartesian chart for a 0D chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.Cart0D().cartesian, cxc.Cart0D)
True

check_data(data: CDictT, /, *, keys: bool = True, values: bool = False)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys (bool) – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.Abstract1D#

Marker flag for 1D representations.

A 1D representation has exactly one coordinate component. Examples include Cartesian $(x)$ or radial $(r)$ coordinates.

class coordinax.charts.Cart1D(*, M: MT = Rn(1))#

Bases: AbstractFixedComponentsChart[MT, tuple[Literal[‘x’]], tuple[Literal[‘length’]]], Abstract1D

One-dimensional Cartesian chart $(x)$.

Components are ordered as ("x",) with dimension ("length",).

This chart is the canonical 1D Cartesian chart and is returned by {func}`coordinax.charts.cartesian_chart` for 1D charts.

Examples

>>> import coordinax.charts as cxc
>>> cxc.cart1d.components
('x',)

>>> cxc.cart1d.coord_dimensions
('length',)

>>> isinstance(cxc.cartesian_chart(cxc.cart1d), cxc.Cart1D)
True

Parameters:: M (TypeVar(MT, bound= AbstractManifold))

M: MT = Rn(1)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

property cartesian: Self#

Return the canonical Cartesian chart for a 1D chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.Cart1D().cartesian, cxc.Cart1D)
True

check_data(data: CDictT, /, *, keys: bool = True, values: bool = False)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys (bool) – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.Radial1D(*, M: MT = Rn(1))#

Bases: AbstractFixedComponentsChart[MT, tuple[Literal[‘r’]], tuple[Literal[‘length’]]], Abstract1D

One-dimensional radial chart $(r)$.

Components are ordered as ("r",) with dimension ("length",).

This chart is semantically equivalent to {class}`coordinax.charts.Cart1D` but uses r instead of x. Its canonical Cartesian projection is {obj}`coordinax.charts.cart1d`.

Examples

>>> import coordinax.charts as cxc
>>> cxc.radial1d.components
('r',)

>>> cxc.radial1d.coord_dimensions
('length',)

>>> isinstance(cxc.cartesian_chart(cxc.radial1d), cxc.Cart1D)
True

Parameters:: M (TypeVar(MT, bound= AbstractManifold))

M: MT = Rn(1)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

property cartesian: Cart1D[MT]#

Return the canonical Cartesian chart for a 1D radial chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.Radial1D().cartesian, cxc.Cart1D)
True

check_data(data: CDictT, /, *, keys: bool = True, values: bool = False)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys (bool) – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.Time1D(*, M: MT = Rn(1))#

Bases: AbstractFixedComponentsChart[MT, tuple[Literal[‘t’]], tuple[Literal[‘time’]]], Abstract1D

One-dimensional time chart (t).

Components are ordered as ("t",) with dimension ("time",).

This chart is the canonical 1D time chart and is often used as the first factor in spacetime product charts.

Examples

>>> import coordinax.charts as cxc
>>> cxc.time1d.components
('t',)

>>> cxc.time1d.coord_dimensions
('time',)

>>> isinstance(cxc.cartesian_chart(cxc.time1d), cxc.Time1D)
True

Parameters:: M (TypeVar(MT, bound= AbstractManifold))

M: MT = Rn(1)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

property cartesian: Time1D#

Return the canonical Cartesian chart for a 1D time chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.Time1D().cartesian, cxc.Time1D)
True

check_data(data: CDictT, /, *, keys: bool = True, values: bool = False)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys (bool) – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.Abstract2D#

Marker flag for 2D representations.

A 2D representation has exactly two coordinate components. This does not imply that the underlying manifold is flat; for example, the two-sphere uses two angular coordinates but represents a curved surface.

class coordinax.charts.Cart2D(*, M: MT = Rn(2))#

Bases: AbstractFixedComponentsChart[MT, tuple[Literal[‘x’], Literal[‘y’]], tuple[Literal[‘length’], Literal[‘length’]]], Abstract2D

Two-dimensional Cartesian chart $(x, y)$.

Components are ordered as ("x", "y") with dimensions ("length", "length").

This chart is the canonical 2D Cartesian chart and is returned by {func}`coordinax.charts.cartesian_chart` for 2D charts.

Examples

>>> import coordinax.charts as cxc
>>> cxc.cart2d.components
('x', 'y')

>>> cxc.cart2d.coord_dimensions
('length', 'length')

>>> isinstance(cxc.cartesian_chart(cxc.cart2d), cxc.Cart2D)
True

Parameters:: M (TypeVar(MT, bound= AbstractManifold))

M: MT = Rn(2)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

property cartesian: Self#

Return the canonical Cartesian chart for a 2D chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.Cart2D().cartesian, cxc.Cart2D)
True

check_data(data: CDictT, /, *, keys: bool = True, values: bool = False)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys (bool) – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.Polar2D(*, M: MT = Rn(2))#

Bases: AbstractFixedComponentsChart[MT, tuple[Literal[‘r’], Literal[‘theta’]], tuple[Literal[‘length’], Literal[‘angle’]]], Abstract2D

Two-dimensional polar chart $(r, theta)$.

Components are ordered as ("r", "theta") with dimensions ("length", "angle").

This chart has direct transitions with {class}`coordinax.charts.Cart2D` and its canonical Cartesian projection is {obj}`coordinax.charts.cart2d`.

Examples

>>> import coordinax.charts as cxc
>>> cxc.polar2d.components
('r', 'theta')

>>> cxc.polar2d.coord_dimensions
('length', 'angle')

>>> isinstance(cxc.cartesian_chart(cxc.polar2d), cxc.Cart2D)
True

Parameters:: M (TypeVar(MT, bound= AbstractManifold))

M: MT = Rn(2)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

property cartesian: Cart2D[MT]#

Return the canonical Cartesian chart for a 2D chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.Cart2D().cartesian, cxc.Cart2D)
True

check_data(data: CDictT, /, *, keys: bool = True, values: bool = False)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys (bool) – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.Abstract3D#

Marker flag for 3D representations.

A 3D representation has exactly three coordinate components. These may parameterize Euclidean space (Cartesian), curvilinear coordinates (cylindrical, spherical), or other three-dimensional manifolds.

class coordinax.charts.Cart3D(*, M: MT = Rn(3))#

Bases: AbstractFixedComponentsChart[MT, tuple[Literal[‘x’], Literal[‘y’], Literal[‘z’]], tuple[Literal[‘length’], Literal[‘length’], Literal[‘length’]]], Abstract3D

Three-dimensional Cartesian chart $(x, y, z)$.

Components are ordered as ("x", "y", "z") with dimensions ("length", "length", "length").

This chart is the canonical 3D Cartesian chart and is returned by {func}`coordinax.charts.cartesian_chart` for 3D charts.

Examples

>>> import coordinax.charts as cxc
>>> cxc.cart3d.components
('x', 'y', 'z')

>>> cxc.cart3d.coord_dimensions
('length', 'length', 'length')

>>> isinstance(cxc.cartesian_chart(cxc.cart3d), cxc.Cart3D)
True

Parameters:: M (TypeVar(MT, bound= AbstractManifold))

M: MT = Rn(3)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

property cartesian: Self#

Return the canonical Cartesian chart for a 3D chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.cart3d.cartesian, cxc.Cart3D)
True

check_data(data: CDictT, /, *, keys: bool = True, values: bool = False)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys (bool) – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.Cylindrical3D(*, M: MT = Rn(3))#

Bases: AbstractFixedComponentsChart[MT, tuple[Literal[‘rho’], Literal[‘phi’], Literal[‘z’]], tuple[Literal[‘length’], Literal[‘angle’], Literal[‘length’]]], Abstract3D

Three-dimensional cylindrical chart $(rho, phi, z)$.

Components are ordered as ("rho", "phi", "z") with dimensions ("length", "angle", "length").

This chart has direct transitions with {class}`coordinax.charts.Cart3D` and its canonical Cartesian projection is {obj}`coordinax.charts.cart3d`.

Examples

>>> import coordinax.charts as cxc
>>> cxc.cyl3d.components
('rho', 'phi', 'z')

>>> cxc.cyl3d.coord_dimensions
('length', 'angle', 'length')

>>> isinstance(cxc.cartesian_chart(cxc.cyl3d), cxc.Cart3D)
True

Parameters:: M (TypeVar(MT, bound= AbstractManifold))

M: MT = Rn(3)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

property cartesian: Cart3D[MT]#

Return the canonical Cartesian chart for a 3D cylindrical chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.Cylindrical3D().cartesian, cxc.Cart3D)
True

check_data(data: CDictT, /, *, keys: bool = True, values: bool = False)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys (bool) – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.AbstractSpherical3D#

Bases: AbstractFixedComponentsChart[MT, Ks, Ds], Abstract3D

Abstract spherical vector representation.

M: MT = Rn(3)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

property cartesian: Cart3D[MT]#

Return the canonical Cartesian chart for a 3D chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.Spherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.LonLatSpherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.MathSpherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.LonCosLatSpherical3D().cartesian, cxc.Cart3D)
True

check_data(data: CDictT, /, *, keys: bool = True, values: bool = False)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys (bool) – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.Spherical3D(*, M: MT = Rn(3))#

Bases: AbstractSpherical3D[MT, tuple[Literal[‘r’], Literal[‘theta’], Literal[‘phi’]], tuple[Literal[‘length’], Literal[‘angle’], Literal[‘angle’]]]

Three-dimensional spherical coordinates $(r, theta, phi)$.

The Cartesian embedding is

$x = rsinthetacosphi,$ $y = rsinthetasinphi,$ $z = rcostheta.$

Here $r ge 0$, $theta in [0,pi]$ is the polar (colatitude) angle, and $phi$ is the azimuth.

This convention matches the physics / mathematics definition of spherical coordinates.

Examples

>>> import coordinax.charts as cxc
>>> cxc.sph3d.components
('r', 'theta', 'phi')

>>> cxc.sph3d.coord_dimensions
('length', 'angle', 'angle')

>>> isinstance(cxc.cartesian_chart(cxc.sph3d), cxc.Cart3D)
True

Parameters:: M (TypeVar(MT, bound= AbstractManifold))

M: MT = Rn(3)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

check_data(data: CDictT, /, *, values: bool = False, **kw: Any)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.
kw (Any)

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property cartesian: Cart3D[MT]#

Return the canonical Cartesian chart for a 3D chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.Spherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.LonLatSpherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.MathSpherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.LonCosLatSpherical3D().cartesian, cxc.Cart3D)
True

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.LonLatSpherical3D(*, M: MT = Rn(3))#

Bases: AbstractSpherical3D[MT, tuple[Literal[‘lon’], Literal[‘lat’], Literal[‘distance’]], tuple[Literal[‘angle’], Literal[‘angle’], Literal[‘length’]]]

Longitude-latitude spherical coordinates.

Components are $(mathrm{lon}, mathrm{lat}, r)$ where:

lon is the azimuthal angle in the equatorial plane,
lat is the latitude in $[-pi/2, pi/2]$,
r is the radial distance.

Relation to standard spherical coordinates:

$mathrm{lat} = pi/2 - theta$, $mathrm{lon} = \phi$.

Examples

>>> import coordinax.charts as cxc
>>> cxc.lonlat_sph3d.components
('lon', 'lat', 'distance')

>>> cxc.lonlat_sph3d.coord_dimensions
('angle', 'angle', 'length')

>>> isinstance(cxc.cartesian_chart(cxc.lonlat_sph3d), cxc.Cart3D)
True

Parameters:: M (TypeVar(MT, bound= AbstractManifold))

M: MT = Rn(3)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

check_data(data: CDictT, /, *, values: bool = False, **kw: Any)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.
kw (Any)

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property cartesian: Cart3D[MT]#

Return the canonical Cartesian chart for a 3D chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.Spherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.LonLatSpherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.MathSpherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.LonCosLatSpherical3D().cartesian, cxc.Cart3D)
True

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.LonCosLatSpherical3D(*, M: MT = Rn(3))#

Bases: AbstractSpherical3D[MT, tuple[Literal[‘lon_coslat’], Literal[‘lat’], Literal[‘distance’]], tuple[Literal[‘angle’], Literal[‘angle’], Literal[‘length’]]]

Longitude-cos(latitude) spherical coordinates.

Components are $(mathrm{lon}cosmathrm{lat}, mathrm{lat}, r)$. This form is sometimes used to improve numerical behavior near the poles, since $cos(mathrm{lat}) to 0$ as $|mathrm{lat}| to pi/2$.

Examples

>>> import coordinax.charts as cxc
>>> cxc.loncoslat_sph3d.components
('lon_coslat', 'lat', 'distance')

>>> cxc.loncoslat_sph3d.coord_dimensions
('angle', 'angle', 'length')

>>> isinstance(cxc.cartesian_chart(cxc.loncoslat_sph3d), cxc.Cart3D)
True

Parameters:: M (TypeVar(MT, bound= AbstractManifold))

M: MT = Rn(3)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

check_data(data: CDictT, /, *, values: bool = False, **kw: Any)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.
kw (Any)

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property cartesian: Cart3D[MT]#

Return the canonical Cartesian chart for a 3D chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.Spherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.LonLatSpherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.MathSpherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.LonCosLatSpherical3D().cartesian, cxc.Cart3D)
True

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.MathSpherical3D(*, M: MT = Rn(3))#

Bases: AbstractSpherical3D[MT, tuple[Literal[‘r’], Literal[‘theta’], Literal[‘phi’]], tuple[Literal[‘length’], Literal[‘angle’], Literal[‘angle’]]]

Mathematical-convention spherical coordinates $(r, theta, phi)$.

In this convention:

$phi$ is the polar angle measured from the positive $z$ axis,
$theta$ is the azimuthal angle in the $xy$-plane.

This differs from the physics convention used by {class}`coordinax.charts.Spherical3D`, where $theta$ and $phi$ are swapped.

Examples

>>> import coordinax.charts as cxc
>>> cxc.math_sph3d.components
('r', 'theta', 'phi')

>>> cxc.math_sph3d.coord_dimensions
('length', 'angle', 'angle')

>>> isinstance(cxc.cartesian_chart(cxc.math_sph3d), cxc.Cart3D)
True

Parameters:: M (TypeVar(MT, bound= AbstractManifold))

M: MT = Rn(3)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

check_data(data: CDictT, /, *, values: bool = False, **kw: Any)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.
kw (Any)

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property cartesian: Cart3D[MT]#

Return the canonical Cartesian chart for a 3D chart.

>>> import coordinax.charts as cxc
>>> isinstance(cxc.Spherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.LonLatSpherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.MathSpherical3D().cartesian, cxc.Cart3D)
True
>>> isinstance(cxc.LonCosLatSpherical3D().cartesian, cxc.Cart3D)
True

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.ProlateSpheroidal3D(*, Delta: ]], M: MT = Rn(3))#

Bases: Abstract3D, AbstractFixedComponentsChart[MT, tuple[Literal[‘mu’], Literal[‘nu’], Literal[‘phi’]], tuple[Literal[‘area’], Literal[‘area’], Literal[‘angle’]]]

Prolate spheroidal coordinates $(mu, nu, phi)$ with focal length $Delta$.

These coordinates are adapted to systems with two foci separated by distance $2Delta$.

Validity constraints enforced by this representation:

$Delta > 0$,
$mu ge Delta^2$,
$|nu| le Delta^2$.

The parameter $Delta$ is stored as metadata on the representation.

Examples

>>> import coordinax.charts as cxc
>>> import unxt as u
>>> chart = cxc.ProlateSpheroidal3D(Delta=u.StaticQuantity(2, "kpc"))
>>> chart.components
('mu', 'nu', 'phi')

>>> chart.coord_dimensions
('area', 'area', 'angle')

>>> isinstance(cxc.cartesian_chart(chart), cxc.Cart3D)
True

>>> d = {"mu": u.Q(4, "kpc2"), "nu": u.Q(0.1, "kpc2"), "phi": u.Q(1, "rad")}
>>> chart.check_data(d)  # doesn't raise
{'mu': Q(4, 'kpc2'), 'nu': Q(0.1, 'kpc2'), 'phi': Q(1, 'rad')}

Parameters:

Delta (Real[StaticQuantity, ''])
M (TypeVar(MT, bound= AbstractManifold))

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

Delta: value > 0]]#: Focal length of the coordinate system.

M: MT = Rn(3)#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

check_data(data: CDictT, /, *, values: bool = False, **kw: Any)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.
kw (Any)

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property cartesian: Cart3D[MT]#

Return the canonical Cartesian chart for a 3D chart.

>>> import coordinax.charts as cxc
>>> import unxt as u

>>> chart = cxc.ProlateSpheroidal3D(Delta=u.StaticQuantity(2, "kpc"))
>>> isinstance(chart.cartesian, cxc.Cart3D)
True

class coordinax.charts.Abstract4D#

Marker flag for 4-D representations.

A 4-D representation has exactly four coordinate components. The primary example is the Minkowski spacetime chart (ct, x, y, z).

class coordinax.charts.Abstract6D#

Marker flag for 6-D representations.

An 6-D representation has an arbitrary number of coordinate components. Examples include Cartesian representations in arbitrary dimensions.

class coordinax.charts.PoincarePolar6D(*, M: AbstractManifold = NoManifold())#

Bases: AbstractFixedComponentsChart[Any, tuple[Literal[‘rho’], Literal[‘pp_phi’], Literal[‘z’], Literal[‘dt_rho’], Literal[‘dt_pp_phi’], Literal[‘dt_z’]], tuple[Literal[‘length’], Literal[‘length / time**0.5’], Literal[‘length’], Literal[‘speed’], Literal[‘length / time**1.5’], Literal[‘speed’]]], Abstract6D

Six-dimensional Poincare-polar chart.

Components are ordered as $(rho,;mathrm{pp_phi},;z,;dotrho,;dot{mathrm{pp_phi}},;dot z)$ with dimensions $(mathrm{length},;mathrm{length}/mathrm{time}^{1/2},;mathrm{length},;mathrm{speed},;mathrm{length}/mathrm{time}^{3/2},;mathrm{speed})$.

Examples

>>> import coordinax.charts as cxc
>>> cxc.poincarepolar6d.components
('rho', 'pp_phi', 'z', 'dt_rho', 'dt_pp_phi', 'dt_z')

>>> cxc.poincarepolar6d.coord_dimensions
('length', 'length / time**0.5', 'length', 'speed', 'length / time**1.5', 'speed')

>>> isinstance(cxc.poincarepolar6d, cxc.PoincarePolar6D)
True

Parameters:: M (AbstractManifold)

M: AbstractManifold = NoManifold()#

The manifold that this chart belongs to.

Default is no_manifold for charts that do not belong to any manifold.

property cartesian: NoReturn#: PoincarePolar6D has no global Cartesian 6D representation.

check_data(data: CDictT, /, *, keys: bool = True, values: bool = False)#

Check that the data is compatible with the chart.

Parameters:

data (TypeVar(CDictT, bound= dict[str, Any])) – The data to check.
keys (bool) – Whether to check that the keys of data match chart.components. If False, this check is skipped. Default is True.
values (bool) – Whether to check that the dimensions of the values in data match chart.coord_dimensions. If False, this check is skipped. Default is False.

Return type:

TypeVar(CDictT, bound= dict[str, Any])

property components: Ks#: The names of the components.

property coord_dimensions: Ds#: The dimensions of the components.

property ndim: int#: Number of coordinate components (chart dimension).

class coordinax.charts.AbstractND#