API Reference¶

Core Classes¶

Core Superellipse class.

class superellipse.core.Superellipse(a=1.0, b=1.0, p=2.0, q=None)[source]¶

Bases: object

A superellipse (Lamé curve) defined by |x/a|^p + |y/b|^q = 1.

Parameters:

a (float) – Semi-axis in x direction (default 1.0)
b (float) – Semi-axis in y direction (default 1.0)
p (float) – Exponent for x term (default 2.0, giving an ellipse)
q (float, optional) – Exponent for y term. If None, uses q=p.

Examples

>>> curve = Superellipse(a=1, b=1, p=4)  # squircle
>>> curve = Superellipse(a=2, b=1, p=2)  # ellipse with aspect 2:1
>>> curve = Superellipse(a=1, b=1, p=20) # nearly a square

a: float = 1.0¶

b: float = 1.0¶

p: float = 2.0¶

q: float | None = None¶

property is_symmetric: bool¶: True if p == q.

property is_ellipse: bool¶: True if p == q == 2.

property is_squircle: bool¶: True if p == q == 4 and a == b.

point(t)[source]¶

Evaluate curve at parameter t ∈ [0, 2π].

Returns shape (2,) if t is scalar, else (N, 2).

Parameters:: t (ndarray[tuple[Any, ...], dtype[floating]] | float)
Return type:: ndarray[tuple[Any, …], dtype[floating]]

tangent(t)[source]¶

Unit tangent vector at parameter t.

Parameters:: t (ndarray[tuple[Any, ...], dtype[floating]] | float)
Return type:: ndarray[tuple[Any, …], dtype[floating]]

normal(t)[source]¶

Outward unit normal at parameter t.

Parameters:: t (ndarray[tuple[Any, ...], dtype[floating]] | float)
Return type:: ndarray[tuple[Any, …], dtype[floating]]

curvature(t)[source]¶

Signed curvature κ at parameter t.

Parameters:: t (ndarray[tuple[Any, ...], dtype[floating]] | float)
Return type:: ndarray[tuple[Any, …], dtype[floating]]

sample(n=100, method='uniform', **kwargs)[source]¶

Sample n points on the curve.

Parameters:

n (int) – Number of points
method (str) – ‘uniform’: uniform in parameter t ‘arclength’: uniform in arc length ‘adaptive’: refine near high curvature

Returns:

points

Return type:

ndarray, shape (n, 2)

panel_discretization(panels_per_quadrant=4, nodes_per_panel=16, beta=8.0)[source]¶

Create a panel-based discretization for boundary integral methods.

Parameters:

panels_per_quadrant (int) – Number of panels per quadrant (total = 4 * this)
nodes_per_panel (int) – Gauss-Legendre nodes per panel
beta (float) – Corner refinement parameter (larger = more refinement near corners)

Returns:

Object containing points, normals, weights, curvature

Return type:

PanelDiscretization

arc_length(t0=0.0, t1=None, n=1000)[source]¶

Compute arc length from t0 to t1 by numerical integration.

If t1 is None, computes full perimeter.

Parameters:

t0 (float)
t1 (float | None)
n (int)

Return type:

float

signed_distance(points)[source]¶

Signed distance from points to curve (negative inside).

Parameters:: points (ndarray[tuple[Any, ...], dtype[floating]])
Return type:: ndarray[tuple[Any, …], dtype[floating]]

contains(points)[source]¶

Test if points are inside the curve.

Parameters:: points (ndarray[tuple[Any, ...], dtype[floating]])
Return type:: ndarray[tuple[Any, …], dtype[bool]]

to_svg_path(n=100, closed=True)[source]¶

Export as SVG path data string.

Returns a string like “M x0 y0 L x1 y1 … Z”

Parameters:

n (int)
closed (bool)

Return type:

str

to_json()[source]¶

Export curve parameters as JSON.

Return type:: str

classmethod from_json(s)[source]¶

Create from JSON string.

Parameters:: s (str)
Return type:: Superellipse

Geometry Functions¶

Geometric computations for superellipses.

superellipse.geometry.superellipse_point(t, a, b, p, q=None)[source]¶

Evaluate superellipse at parameter t ∈ [0, 2π].

Parametric form:: x(t) = a * sign(cos t) * |cos t|^(2/p) y(t) = b * sign(sin t) * |sin t|^(2/q)

Parameters:

t (ndarray[tuple[Any, ...], dtype[floating]] | float)
a (float)
b (float)
p (float)
q (float | None)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

superellipse.geometry.superellipse_derivative(t, a, b, p, q=None)[source]¶

First derivative dr/dt of superellipse parametric form.

Parameters:

t (ndarray[tuple[Any, ...], dtype[floating]] | float)
a (float)
b (float)
p (float)
q (float | None)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

superellipse.geometry.superellipse_second_derivative(t, a, b, p, q=None)[source]¶

Second derivative d²r/dt² of superellipse parametric form.

Parameters:

t (ndarray[tuple[Any, ...], dtype[floating]] | float)
a (float)
b (float)
p (float)
q (float | None)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

superellipse.geometry.superellipse_tangent(t, a, b, p, q=None)[source]¶

Unit tangent vector at parameter t.

Parameters:

t (ndarray[tuple[Any, ...], dtype[floating]] | float)
a (float)
b (float)
p (float)
q (float | None)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

superellipse.geometry.superellipse_normal(t, a, b, p, q=None)[source]¶

Outward unit normal at parameter t (90° CCW rotation of tangent).

Parameters:

t (ndarray[tuple[Any, ...], dtype[floating]] | float)
a (float)
b (float)
p (float)
q (float | None)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

superellipse.geometry.superellipse_curvature(t, a, b, p, q=None)[source]¶

Signed curvature κ = (x’y’’ - y’x’’) / (x’² + y’²)^(3/2).

Parameters:

t (ndarray[tuple[Any, ...], dtype[floating]] | float)
a (float)
b (float)
p (float)
q (float | None)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

superellipse.geometry.curvature_from_derivatives(dy_dx, d2y_dx2)[source]¶

Curvature for a graph y = f(x): κ = y’’ / (1 + y’²)^(3/2).

Parameters:

dy_dx (ndarray[tuple[Any, ...], dtype[floating]])
d2y_dx2 (ndarray[tuple[Any, ...], dtype[floating]])

Return type:

ndarray[tuple[Any, …], dtype[floating]]

superellipse.geometry.signed_distance_superellipse(points, a, b, p, q=None)[source]¶

Approximate signed distance from points to superellipse.

Negative inside, positive outside. Uses the implicit form for a fast approximation.

Parameters:

points (ndarray[tuple[Any, ...], dtype[floating]])
a (float)
b (float)
p (float)
q (float | None)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

superellipse.geometry.lame_y_of_x(x, n, a)[source]¶

For Lamé curve x^{2n} + (y/a)^{2n} = 1, compute y from x ∈ [0,1].

Parameters:

x (ndarray[tuple[Any, ...], dtype[floating]])
n (int)
a (float)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

superellipse.geometry.lame_dy_dx(x, n, a)[source]¶

Derivative dy/dx for Lamé curve in first quadrant.

Parameters:

x (ndarray[tuple[Any, ...], dtype[floating]])
n (int)
a (float)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

superellipse.geometry.lame_d2y_dx2(x, n, a)[source]¶

Second derivative d²y/dx² for Lamé curve in first quadrant.

Parameters:

x (ndarray[tuple[Any, ...], dtype[floating]])
n (int)
a (float)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

Discretization¶

Discretization methods for superellipses.

superellipse.discretize.uniform_sample(n)[source]¶

Return n uniformly spaced parameter values in [0, 2π).

Parameters:: n (int)
Return type:: ndarray[tuple[Any, …], dtype[floating]]

superellipse.discretize.arclength_sample(n, a, b, p, q=None, oversample=10)[source]¶

Return n parameter values uniformly spaced in arc length.

Uses oversampling and interpolation for accuracy.

Parameters:

n (int)
a (float)
b (float)
p (float)
q (float | None)
oversample (int)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

superellipse.discretize.adaptive_sample(n, a, b, p, q=None, curvature_weight=0.5)[source]¶

Return n parameter values with adaptive refinement near high curvature.

Blends uniform and curvature-based sampling.

Parameters:

n (int)
a (float)
b (float)
p (float)
q (float | None)
curvature_weight (float)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

superellipse.discretize.panel_nodes_weights(a0, a1, m)[source]¶

m-point Gauss-Legendre nodes/weights mapped from [-1,1] to [a0,a1].

Parameters:

a0 (float)
a1 (float)
m (int)

Return type:

tuple[ndarray[tuple[Any, …], dtype[_ScalarT]], ndarray[tuple[Any, …], dtype[_ScalarT]]]

superellipse.discretize.split_interval(a0, a1, num_panels)[source]¶

Uniform split of [a0,a1] into num_panels subintervals.

Parameters:

a0 (float)
a1 (float)
num_panels (int)

Return type:

list[tuple[float, float]]

class superellipse.discretize.PanelDiscretization(points, normals, weights, curvature)[source]¶

Bases: object

Panel-based boundary discretization for BIE methods.

Parameters:

points (ndarray[tuple[Any, ...], dtype[floating]])
normals (ndarray[tuple[Any, ...], dtype[floating]])
weights (ndarray[tuple[Any, ...], dtype[floating]])
curvature (ndarray[tuple[Any, ...], dtype[floating]])

points¶

Boundary nodes in CCW order

Type:: ndarray, shape (N, 2)

normals¶

Outward unit normals at each node

Type:: ndarray, shape (N, 2)

weights¶

Quadrature weights (ds measure)

Type:: ndarray, shape (N,)

curvature¶

Signed curvature at each node

Type:: ndarray, shape (N,)

points: ndarray[tuple[Any, ...], dtype[floating]]¶

normals: ndarray[tuple[Any, ...], dtype[floating]]¶

weights: ndarray[tuple[Any, ...], dtype[floating]]¶

curvature: ndarray[tuple[Any, ...], dtype[floating]]¶

property n_nodes: int¶

classmethod from_superellipse(a, b, p, q=None, panels_per_quadrant=4, nodes_per_panel=16, beta=8.0)[source]¶

Build panel discretization for symmetric superellipse (Lamé curve).

For now, only supports symmetric case p = q = 2n (integer n). Uses x-parameterization in first quadrant with corner refinement.

Parameters:

a (float) – Semi-axes (for Lamé, typically a=1, b=aspect)
b (float) – Semi-axes (for Lamé, typically a=1, b=aspect)
p (float) – Exponents (must be equal integers * 2 for Lamé)
q (float) – Exponents (must be equal integers * 2 for Lamé)
panels_per_quadrant (int) – Number of panels per quadrant
nodes_per_panel (int) – Gauss-Legendre nodes per panel
beta (float) – Corner refinement parameter

Return type:

PanelDiscretization