Skip to main content

ultrasphere

CI Status Documentation Status

Test coverage percentage uv Ruff prek

PyPI Version Supported Python versions License


Documentation: https://ultrasphere.readthedocs.io

Source Code: https://github.com/ultrasphere-dev/ultrasphere


Vilenkin–Kuznetsov–Smorodinsky (VKS) polyspherical (hyperspherical) coordinates in NumPy / PyTorch

Installation

Install this via pip (or your favourite package manager):

pip install ultrasphere[plot]

Usage

Spherical Coordinates ↔ Cartesian Coordinates

First import the module and create a spherical coordinates object.

>>> import ultrasphere as us
>>> from array_api_compat import numpy as np
>>> from array_api_compat import torch
>>> rng = np.random.default_rng(0)
>>> c = us.create_spherical()

Getting spherical coordinates from cartesian coordinates:

>>> spherical = c.from_cartesian(torch.asarray([1.0, 2.0, 3.0]))
>>> spherical
{'r': tensor(3.7417), 'phi': tensor(1.1071), 'theta': tensor(0.6405)}

Getting cartesian coordinates from spherical coordinates:

>>> c.to_cartesian(spherical)
{0: tensor(1.), 1: tensor(2.0000), 2: tensor(3.)}

Using various VKS polyspherical coordinates

>>> us.create_polar()
SphericalCoordinates(a)
>>> us.create_spherical()
SphericalCoordinates(ba)
>>> us.create_standard(3)
SphericalCoordinates(bba)
>>> us.create_standard_prime(4)
SphericalCoordinates(b'b'b'a)
>>> us.create_hopf(3)
SphericalCoordinates(ccaacaa)
>>> us.create_from_branching_types("cbab'a")
SphericalCoordinates(cbab'a)
>>> us.create_random(10, rng=rng)
SphericalCoordinates(cacccaaaba)

One can convert between Cartesian coordinates and VKS polyspherical coordinates in the same way as above.

The name of the spherical nodes and cartesian nodes can be obtained by:

>>> c = us.create_standard(5)
>>> c.s_nodes
['theta0', 'theta1', 'theta2', 'theta3', 'theta4']
>>> c.s_ndim
5
>>> c.c_nodes
[0, 1, 2, 3, 4, 5]
>>> c.c_ndim
6

"r" is a special node which represents the radius and is not included in s_nodes.

The definition and notation of VKS polyspherical coordinates follows [Cohl2012, Appendix B]. Following sections would also help understand the VKS polyspherical coordinates.

  • [Cohl2012] Cohl, H. (2012). Fourier, Gegenbauer and Jacobi Expansions for a Power-Law Fundamental Solution of the Polyharmonic Equation and Polyspherical Addition Theorems. Symmetry, Integrability and Geometry: Methods and Applications (SIGMA), 9. https://doi.org/10.3842/SIGMA.2013.042

Drawing spherical coordinates using rooted trees (Vilenkin's method of trees)

Python

>>> c = us.create_from_branching_types("ccabbab'b'ba")
>>> us.draw(c)
(6.5, 3.5)

CLI

ultrasphere "ccabbab'b'ba"

Output:

ccabbab'b'ba

The image shows how Cartesian coordinates (leaf nodes) are calculated from spherical coordinates (internal nodes).

For example, $x_{10}$, corresponding to node 10, is a leaf node which ancestors are [θ0, θ2, θ7, θ8, θ9]. The edges which connect these nodes are named [sin, cos, cos, sin, sin], respectively. Thus, $x_{10}$ is calculated as:

$$ x_{10} = \sin \theta_0 \cos \theta_2 \cos \theta_7 \sin \theta_8 \sin \theta_9 $$

Integration over sphere using spherical coordinates

>>> c = us.create_spherical()
>>> f = lambda spherical: spherical["theta"] ** 2 * spherical["phi"]
>>> np.round(us.integrate(
...     c,
...     f,
...     False, # does not support separation of variables
...     10, # number of quadrature points
...     xp=np # the array namespace
... ), 5)
np.float64(110.02621)

Random sampling

Sampling random points uniformly from the unit ball:

>>> c = us.create_spherical()
>>> points_ball = us.random_ball(c, shape=(), xp=np, rng=rng)
>>> points_ball
array([0.12504754, 0.45095196, 0.32752147])
>>> np.linalg.vector_norm(points_ball)
np.float64(0.5711960026239531)

Sampling random points uniformly from the sphere (does not include interior points):

>>> points_sphere = us.random_ball(c, shape=(), xp=np, surface=True, rng=rng)
>>> points_sphere
array([-0.89670228, -0.44166441,  0.02928439])
>>> np.linalg.vector_norm(points_sphere)
np.float64(1.0)

References

Metadata

Release files for ultrasphere 2.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ultrasphere 2.1.0
File Size Uploaded Provenance Actions
ultrasphere-2.1.0.tar.gz 25.1 kB With provenance Details for ultrasphere-2.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ultrasphere 2.1.0
File Interpreter ABI Platform Actions
ultrasphere-2.1.0-py3-none-any.whl Python 3 none any Details for ultrasphere-2.1.0-py3-none-any.whl

Total release size: 48.4 kB

Release files / ultrasphere-2.1.0.tar.gz

Download URL ultrasphere-2.1.0.tar.gz
Size 25.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a7febf5a7031c8d215bf5eec9e7f9e8547834e359c1b35788c10a4dc6496c62e
BLAKE2b-256 checksum
How to use checksums
ed4cfd557b7b77ed13f41ef9038df764e37d0cef4ce2fe0f8b302e5fd6eded61
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Release files / ultrasphere-2.1.0-py3-none-any.whl

Download URL ultrasphere-2.1.0-py3-none-any.whl
Size 23.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7edb2a28907976646ce79ba47ac56b13d5e19a9cc416be027dee75a61523c9a2
BLAKE2b-256 checksum
How to use checksums
bf0f7cd71d488fb966e2bd817e7527199173d5a1bd0787f59ca37c465f41dcdf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Security for ultrasphere 2.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ultrasphere-2.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page