103 lines
3.8 KiB
TypeScript
103 lines
3.8 KiB
TypeScript
/**
|
|
* Hyperbolic Embedding Utilities
|
|
*
|
|
* Convert Euclidean embeddings to hyperbolic (Poincaré ball) space
|
|
* for better representation of hierarchical relationships.
|
|
*
|
|
* Features:
|
|
* - Euclidean to Poincaré ball conversion
|
|
* - Hyperbolic distance metrics
|
|
* - Mobius operations (addition, scalar multiplication)
|
|
* - Exponential and logarithmic maps
|
|
*
|
|
* References:
|
|
* - Nickel & Kiela (2017): "Poincaré Embeddings for Learning Hierarchical Representations"
|
|
* - Ganea et al. (2018): "Hyperbolic Neural Networks"
|
|
*/
|
|
/**
|
|
* Hyperbolic geometry configuration
|
|
*/
|
|
export interface HyperbolicConfig {
|
|
/** Curvature of hyperbolic space (default: -1) */
|
|
curvature?: number;
|
|
/** Epsilon for numerical stability (default: 1e-15) */
|
|
epsilon?: number;
|
|
/** Maximum norm to prevent numerical issues (default: 1 - 1e-5) */
|
|
maxNorm?: number;
|
|
}
|
|
/**
|
|
* Convert Euclidean embedding to Poincaré ball
|
|
*
|
|
* Uses exponential map at origin to project Euclidean vectors
|
|
* into the Poincaré ball model of hyperbolic space.
|
|
*
|
|
* @param euclidean - Euclidean embedding vector
|
|
* @param config - Hyperbolic geometry configuration
|
|
* @returns Poincaré ball embedding
|
|
*/
|
|
export declare function euclideanToPoincare(euclidean: Float32Array | number[], config?: HyperbolicConfig): Float32Array;
|
|
/**
|
|
* Convert Poincaré ball embedding back to Euclidean
|
|
*
|
|
* Uses logarithmic map at origin to project back to Euclidean space.
|
|
*
|
|
* @param poincare - Poincaré ball embedding
|
|
* @param config - Hyperbolic geometry configuration
|
|
* @returns Euclidean embedding vector
|
|
*/
|
|
export declare function poincareToEuclidean(poincare: Float32Array | number[], config?: HyperbolicConfig): Float32Array;
|
|
/**
|
|
* Compute hyperbolic distance in Poincaré ball
|
|
*
|
|
* The geodesic distance between two points in the Poincaré ball.
|
|
*
|
|
* @param a - First Poincaré embedding
|
|
* @param b - Second Poincaré embedding
|
|
* @param config - Hyperbolic geometry configuration
|
|
* @returns Hyperbolic distance
|
|
*/
|
|
export declare function hyperbolicDistance(a: Float32Array | number[], b: Float32Array | number[], config?: HyperbolicConfig): number;
|
|
/**
|
|
* Möbius addition in Poincaré ball
|
|
*
|
|
* Hyperbolic "addition" operation that respects the ball geometry.
|
|
*
|
|
* @param a - First vector
|
|
* @param b - Second vector
|
|
* @param config - Configuration
|
|
* @returns a ⊕ b in hyperbolic space
|
|
*/
|
|
export declare function mobiusAdd(a: Float32Array | number[], b: Float32Array | number[], config?: HyperbolicConfig): Float32Array;
|
|
/**
|
|
* Möbius scalar multiplication in Poincaré ball
|
|
*
|
|
* @param r - Scalar
|
|
* @param v - Vector in Poincaré ball
|
|
* @param config - Configuration
|
|
* @returns r ⊗ v in hyperbolic space
|
|
*/
|
|
export declare function mobiusScalarMul(r: number, v: Float32Array | number[], config?: HyperbolicConfig): Float32Array;
|
|
/**
|
|
* Compute hyperbolic centroid (Fréchet mean) of multiple points
|
|
*
|
|
* Uses iterative optimization to find the centroid in Poincaré ball.
|
|
*
|
|
* @param points - Array of Poincaré embeddings
|
|
* @param config - Configuration
|
|
* @param maxIter - Maximum iterations (default: 100)
|
|
* @returns Hyperbolic centroid
|
|
*/
|
|
export declare function hyperbolicCentroid(points: Array<Float32Array | number[]>, config?: HyperbolicConfig, maxIter?: number): Float32Array;
|
|
/**
|
|
* Batch convert Euclidean embeddings to Poincaré ball
|
|
*/
|
|
export declare function batchEuclideanToPoincare(embeddings: Array<Float32Array | number[]>, config?: HyperbolicConfig): Float32Array[];
|
|
/**
|
|
* Compute pairwise hyperbolic distances
|
|
*/
|
|
export declare function pairwiseHyperbolicDistances(embeddings: Float32Array[], config?: HyperbolicConfig): Float32Array;
|
|
/**
|
|
* Check if point is inside Poincaré ball
|
|
*/
|
|
export declare function isInPoincareBall(v: Float32Array | number[], config?: HyperbolicConfig): boolean;
|
|
//# sourceMappingURL=hyperbolic.d.ts.map
|