ganja.js

repository·master·Indexed 23 days ago

https://github.com/enkimute/ganja.js

A Geometric Algebra code generator and library for JavaScript (version 1.0.189) that enables working with Clifford algebras of any signature. It features operator overloading, algebraic literals via an inline translation engine, and a transpiler to generate high-performance implementations in C++, C#, Rust, and Python. The library includes tools for visualizing geometric elements through a graph method and supports various algebras including PGA, CGA, and Quaternions.

Tokens
9.8K
Snippets
16
Records
47
Agent score
81%

What's inside ganja.js

  1. Use Mixed Mode for subalgebra interoperability

    master

    Ganja.js supports mix mode, which allows elements from different subalgebras to inter-operate. When mix: true is set in the options, all operations use basis name access instead of array indexing, and missing blades are automatically substituted with 0 to ensure safety.

    Note: When using mixed mode, it is recommended to use the .Inline function of the 'parent' (larger) algebra to avoid reducing operations to a smaller field prematurely.

  2. Quickstart: 2D Projective Geometric Algebra (PGA2D)

    master

    To get started with 2D PGA (signature 2,0,1), include the ganja.js script and use the following boilerplate. This setup defines points, lines, and geometric operations like join (vee) and meet (wedge), and includes a built-in graph function to render elements in an SVG.

    // Create a Clifford Algebra with 2 positive and one zero generator.
    Algebra(2,0,1,()=>{
        
        // Output algebra info to the console.
        this.describe();
        
        // In dual projectivized space, the origin is represented by the e12 bivector.
        var origin = 1e12, EX=-1e02, EY=1e01;
        
        // Points and lines can be specified directly.
        var point = (x,y)=>origin+x*EX+y*EY;
        var line  = (a,b,c)=>a*1e1+b*1e2+c*1e0;
        
        // Or through join and meet operations.
        var join = (p1,p2)=>p1&p2;
        var meet = (l1,l2)=>l1^l2;
        
        // Distances and angles
        var dist_points     = (P1,P2)=>(P1.Normalized&P2.Normalized).Length;
        var dist_point_line = (P,l)=>((P.Normalized)^(l.Normalized)).e012;
        var angle_lines     = (l1,l2)=>(l1.Normalized<<l2.Normalized).s;
      
        // Points and lines can be projected and rejected.
        var project         = (P,l)=>P<<l*l;
        var parallel        = (P,l)=>P<<l*P;
        var ortho           = (P,l)=>P<<l;
      
        // translations and rotations.
        var rotor           = (a,P)=>Math.cos(a*0.5)+Math.sin(a*0.5)*P;
        var translator      = (x,y)=>1+0.5*(x*1e02-y*1e01); 
        
        // To demonstrate graphing, we create some points and lines.
        var A = point(-1,-1), B = point(1,-1), C = point(-1,1), l = line(-1,1,0.5);
        
        // Ganja.js can directly graph 2D PGA elements.
        document.body.appendChild(this.graph([
          0x444444,
          "title",
          A, B, C, "Label for point",
          l,"Label for line",
          ()=>[A,B], "Label for segment",
          0xffeeee,
          ()=>[A,B,C], 0xff7777,
          ()=>[A,B,C], 0xff7777
        ],{grid:true, animate:false}));
    });
  3. Explore interactive ganja.js examples in the coffeeshop

    master

    You can explore and interact with various geometric algebra implementations without installing anything by visiting the ganja.js coffeeshop. The examples are interactive, allowing you to modify the code online to see real-time changes.

    Key example categories include:

    • Complex Algebra: Mandelbrot sets and least squares.
    • Dual Numbers: Differentiation and backpropagation.
    • Quaternions: Hue and Mandelbrot sets.
    • PGA (Projective Geometric Algebra):
      • 2D (pga2d): Points, lines, distances, angles, rotors, translators, isometries, inverse kinematics, and physics.
      • 3D (pga3d): Points, lines, rotors, translators, skinning, and physics (planets, origami, symmetric tops).
    • CGA (Conformal Geometric Algebra):
      • 2D (cga2d): Points, circles, and rotors.
      • 3D (cga3d): Points, spheres, planes, and intersections.
    • Other: MGA3d, CCGA3d, and QCGA3d examples.
    https://enkimute.github.io/ganja.js/examples/coffeeshop.html
  4. Install and use the Ganja.js code generator

    master

    Ganja.js is a Node.js transpiler that uses templates to generate Geometric Algebra implementations for C++, C#, Rust, and Python. These implementations support any signature and provide clean reference implementations with operator overloading and flat storage.

    Prerequisites

    To compile for all supported languages, ensure you have the following installed:

    • Node.js 11
    • mono
    • C++ (>11)
    • Python
    • Rust (nightly) — run rustup default nightly in the project folder

    Compilation

    To generate and compile all languages and algebras, run:

    make
  5. Try the GAlculator and Wedge game

    master

    ganja.js powers several specialized interactive applications:

    1. GAlculator: A geometric algebra calculator. You can use it online or download it from the Google Play Store.
    2. Wedge Game: A hands-on way to experience the Euclidean plane using Projective Geometric Algebra (PGA). Play it here.
    https://enkimute.github.io/ganja.js/examples/galculator.html
  6. Use generated C++ Geometric Algebra implementations

    master

    The ganja.js code generator produces a collection of C++ algebra implementations. Each generated file provides a class that uses flat storage for efficiency, includes overloaded operators for common Geometric Algebra (GA) operations, and provides simple numerical examples.

    Available algebras include:

    SignatureFilenameName
    0,1c.cppcomplex numbers
    1,0hyperbolic.cpphyperbolic numbers
    0,0,1dual.cppdual numbers
    2,0r2.cpp2D Vectors
    3,0r3.cpp3D Vectors
    1,1mink.cppMinkowski
    0,2quat.cppQuaternion
    3,1spacetime.cppSpacetime
    4,1cga.cppConformal Geometric Algebra
    3,0,1pga3d.cppProjective Geometric Algebra
  7. Generate specific languages or algebras

    master

    You can customize the generation process to target specific languages or specific algebras using the GEN_LANG variable and algebra names as arguments to make.

    Example: Generate multiple languages and algebras

    To generate C#, C++, Python, and Rust for a specific set of algebras (e.g., hyperbolic, dual, r2, r3, mink, quat, r111, spacetime, cga, pga3d):

    make GEN_LANG="csharp cpp python rust" c hyperbolic dual r2 r3 mink quat r111 spacetime cga pga3d

    Example: Generate a single algebra for a single language

    To generate only pga3d for rust:

    make GEN_LANG="rust" pga3d
  8. Install ganja.js via npm or CDN

    master

    You can install ganja.js using npm for Node.js environments or include it directly in the browser via a script tag. The library has no dependencies.

    npm install ganja.js
    <SCRIPT SRC="https://unpkg.com/ganja.js"></SCRIPT>
  9. Use Python algebras generated by ganja.js

    master

    The ganja.js code generator produces Python implementations of various geometric algebras. Each generated file contains a class that implements the specific algebra using flat storage, includes overloaded operators for common Geometric Algebra (GA) operations, and provides simple numerical examples.

    Available algebras include:

    SignatureFilenameName
    0,1c.pycomplex numbers
    1,0hyperbolic.pyhyperbolic numbers
    0,0,1dual.pydual numbers
    2,0r2.py2D Vectors
    3,0r3.py3D Vectors
    1,1mink.pyMinkowski
    0,2quat.pyQuaternion
    3,1spacetime.pySpacetime
    4,1cga.pyConformal Geometric Algebra
    3,0,1pga3d.pyProjective Geometric Algebra
  10. Use generated Rust geometric algebras

    master

    The ganja.js code generator produces high-performance Rust implementations of various geometric algebras. Each generated file provides a class that uses flat storage for efficiency, includes overloaded operators for common Geometric Algebra (GA) operations, and provides simple numerical examples for testing and reference.

    Available algebras include:

    SignatureFilenameName
    0,1c.rscomplex numbers
    1,0hyperbolic.rshyperbolic numbers
    0,0,1dual.rsdual numbers
    2,0r2.rs2D Vectors
    3,0r3.rs3D Vectors
    1,1mink.rsMinkowski
    0,2quat.rsQuaternion
    3,1spacetime.rsSpacetime
    4,1cga.rsConformal Geometric Algebra
    3,0,1pga3d.rsProjective Geometric Algebra
  11. Visualize 1D and 2D functions on a Canvas

    master

    For 1D or 2D functions, ganja.js can render results onto an HTML5 <canvas>.

    • Two-parameter functions: Evaluated for every pixel in the canvas range to create a color map.
    • One-parameter functions: Evaluated across the X range to draw a line representing the function's Y value.
    • Grid Support: If options.grid is true, a coordinate grid with ticks and labels is drawn on the canvas.
    • Range: Controlled via options.range, which defaults to [-1, 1, 1, -1] (x_from, x_to, y_from, y_to).
  12. Visualize geometric elements with SVG rendering

    master

    The engine can render geometric elements (Points, Lines, Circles, Point Pairs, Polygons, and Vectors) as SVG elements. When rendering, the engine handles coordinate transformations, scaling, and color application based on the provided options object.

    Key behaviors:

    • Points: Rendered as <CIRCLE> elements.
    • Lines: Rendered as <LINE> elements.
    • Circles: Rendered as <CIRCLE> elements with fill="none".
    • Point Pairs: Rendered as two <CIRCLE> elements (hollow or filled depending on the square of the magnitude).
    • Polygons: Rendered as <POLYGON> elements if the input is an array of length > 2.
    • Vectors: Rendered as <LINE> elements starting from a point.
    • Labels: Strings are rendered as <text> elements.
    • Colors: Numbers are converted to hex color strings.