DSL4GeometricAlgebra

This repository contains code to work with multivector expressions of geometric algebra. The idea is to realise a complete toolchain with a geometric algebra specific domain specific language based on truffle/graal with state of the art smart editing features, debugging functionality and a fast implementation based on JCasADi.

Disclaimer

The project is in an early state of development, so it is not advised to use it in real world applications. If you have feedback or feature suggestions, please create a new GitHub Issue.

Especially be cautious regarding:

• the documentation may not be up to date.
• breaking changes can occur at any time.

GraalVM Setup

Download GraalVM (23.1.2) for JDK 21 Community 21.0.2 (Linux (amd64), Java21).

Extract the downloaded archive to an arbitrary location.

Netbeans configuration

Add a new java platform with the name "GraalVM". \ If you use Netbeans IDE with newer version than 21 you have to start the IDE with JDK 21 to be able to build because the build configuration is configured to use the default JDK which is the JDK the IDE is started or you can configure explicit the platform to build by following steps and further the project configuration steps:\

• open project properties via right-click on the project
• navigate to Build / Compile
• click "Manage Java Platforms..."

or navigate to this point via the Tools main menu.

• click "Add Platform..."
• In the poping-up wizard:
  • select platform type "Java Standard Edition"
  • choose the platform folder within the extracted archive.
  • name it "GraalVM"

Netbeans project configuration

• open project properties via right-click on the project
• navigate to Build / Compile
• in the drop-down list labeled "Java Platform" choose "GraalVM"

GraalVM Update

Redo the GraalVM Setup with the new version. If you use same path and foldername as before, you can skip the step Netbeans configuration.

If you are the first collaborator updating to a new version, you also need to

• update the download link in this documentation.
• update the graalvm.version property in the pom.xml of the DSL4GA__Parent. Note, that it differs from the JDK Version. "Language runtimes" is the keyword for it in the text of the download page.
• try building the project and fix broken code.

Dependencies Setup

The project depends on the vecmath library in the refactored version of the JogAmp Community. Your can find this library here. Unfortunately there is no maven repository available. That is why you need to download the jar file manually and add it as a local depency of the project. To do this in the nebeans ide: Right-click on the depencies of the project and add the dependency manually. The group id is "org.jogamp.java3d", the artifactId is "vecmath" and the type is "jar". \ Alternatively clone it from GitHub, update the compiler version in it's pom.xml and build it.

Clone and checkout

1. GeometricAlgebra
2. ConformalGeometricAlgebra
3. SparseMatrix
4. CGACasADi

and build those projects to have them available in your local Maven cache. SparseMatrix is a simple Java sparse matrix implementation used primarily as interface between the annotation based Java API and the DSL. So it allows to write code independend from GA-specific objects. CGACasADi is a fast symbolic implementation of CGA based on CasADI. A Java-Wrapper for CasADI based on Swig is used for Java integration.

Run

In order to run the example invokation in the package 'de.dhbw.rahmlab.geomalgelang.App' make sure you successfully executed the steps GraalVM Setup and Dependencies Setup beforehand. \ If you use an IDE other than Netbeans and execute the generated .class files directly rather than the generated .jar file, it might be necessary to configure the Maven execution in your IDE with the same properties set in the nbactions.xml file.

Annotation based API

An annotation based API useful especially for testing is available.

Netbeans IDE Tooling

Syntax-Highlighting

A Syntax-Highlighting plugin for the Netbeans-IDE can be found here.

Insertion of special characters

A Netbeans-IDE plugin which adds a submenu into the context-menu of the editor to insert CGA-specific symbols and operators can be found here.

Implementations

There are two implementations of the API:

• Fast, which will be optimized for runtime -not parsing- performance.
• Truffle, which will be optimized for a good development experience.

Their syntax will be the same in the longrun. However, during development of the language, some syntactical constructs will temporarily not supported by one or the other.

Expressions

• Numeric literals like "0.5" and scalar constants like "π" are in OPNS representation.

Function definitions

Rules

• There needs to be at least one function defined with the name main. Invokations of the program will call this one first.
• Currently, callees need to be defined above the callers.
• In consequence, main needs to be the last function defined.
• Function overloading is currently not supported and will lead to an exception.
• A function will return only the list in the last line of its definition.
• The return value of a call needs to be assigned to a variable.
• An assignment to multiple variables in the same line is possible if the right side consists only of a call.
• The count of the assigned variables must match the count of the result values of a call.
• With an assignment to "_", a return value can be discarded. This is only possible for calls which return at least two values.
• If the right side of an assignment is not only a call but a composed expression, within it are only calls allowed which return exactly one value.

Example

Custom functions can be defined like in the following example:

fn test(a) {
    a, 5
}

fn main(a, b) {
    _, c := test(b)
    a, b, c
}

Visualization

Variables can be visualized after assignment with a preceding colon. For correct visualization, make sure that the variable is in IPNS representation. \ In the following example, the variable b will be visualized:

fn main(a) {
    :b := a
}

Operators

Hint: Operator precedence determines how operators are parsed concerning each other. A higher precedence number results in a higher binding strength. Thus operators with higher precedence become the operands of operators with lower precedence.

Exceptions from the precedence rules:

• Expressions like a-b evaluate to subtraction(a, b) instead of geometric_product(a, negate(b)).

2-ary operators

All 2-ary operators are left-associative.

Base 2-ary operators

Hint: The Unicode and Latex name for the symbol used for left contraction is "RIGHT FLOOR" and for right contraction is "LEFT FLOOR". Please be cautious to this detail when writing Latex or programming tools which work with the language.

Additional 2-ary operators

1-ary operators

All 1-ary operators have higher precedence than 2-ary ones. \ All 1-ary operators are right-sides except from the negate operator '-'. \ Except dual/undual the operators cancel itself so if your write X˜˜ no reverse is executed.

Base 1-ary operators

There exist three types of involution operations: Space inversion, reversion and the combination of both the clifford conjugation.

Additional 1-ary operators

Composite operators

Built-in functions

Base functions

Additional functions to create transformations

Symbols

Base vector symbols

Further symbols

Useful equations between above symbols

ε₀E₀=-ε₀, E₀ε₀=ε₀, εᵢE₀=εᵢ, E₀εᵢ=-εᵢ, E₀²=1, ε₀²=εᵢ²=0, ε₊²=1, ε₋²=-1, ε₊⋅ε₋=0