---

1. Common Syntax Elements

The syntax of GMacDSL is based on some simple common elements:

• Comments: Including the traditional C-like single line comments that start with //  until the end of a line, and multi-line comments between /*  and */
• String Literals: Any series of characters between pairs of double quotes “ ”  or single quotes ‘ ‘  is a string literal, with escape sequences (for example \t, \r, \\, \”, etc.) allowed inside strings. If a string is prefixed by @  it’s a verbatim string that is taken literally with no escape sequences allowed. String literals in GMacDSL are very similar to C# string literals; see this article about C# string literals for more details.
• Identifiers: Used for naming code items in GMacDSL like variables, structures, macros, namespaces, etc. An identifier is any sequence of character letters, digits, or underscore that does not start with a digit.
• Qualified Identifiers: We can concatenate two or more identifiers separated by dots to fully describe a child code item just like member access in common programming languages. For example main.e3d.e1
• Numeric Literals: The standard integers and scientific notation for floating point numbers widely used in many programming languages like C# for example.
• Keywords: We will see GMacDSL keywords throughout this guide like frame, namespace, macro, constant, etc.
• Operators: Many GMacDSL operators exist for computing with Geometric Algebra (GA) and we will see them throughout this guide.

In GMacDSL identifiers, keywords, and operators are case-sensitive.

---

2. Main Code Items

---

3. Namespaces

---

4. Frames

4.1. Frame Basis Blades

When we create a frame a set of basis blades for the frame are automatically defined using the basis vectors. Each basis blade has 3 ways for referencing it inside GMacDSL code:

• The Canonical Name: The outer product of its basis vectors ordered by their appearance in the definition of the frame.
• The Indexed Name: The basis blades of a frame having n basis vectors will have 2^{n} basis blades. The indexed name of a basis blade is E<n>  where <n>  is any integer between 0 and 2^{n}-1.
• The Binary Indexed Name: This is the same as the indexed name but using a binary representation for the index in n-digits. The binary indexed name of a basis blade is B<n>  where <n>  is any integer between 0 and 2^{n}-1 represented as a full n-bit binary number.

4.2. Frame Signature Definition

The signature of a frame can be defined in any one of the following methods:

• euclidean : This will create a Euclidean frame of any dimension depending on the number of basis vectors.
• orthonormal <sig_string> : This will create an orthonormal frame with a diagonal bilinear form matrix having +1 or -1 items on the diagonal. <sig_string>  is a string containing + \ - characters for the basis vectors signatures. It must have the same number of + \ - as the basis vectors of the frame.
• orthogonal <mat_list> : This will create an orthogonal frame with a diagonal bilinear form matrix. The given <mat_list>  is any Mathematica expression that results in a list of constants having the same number of elements as the basis vectors of the frame.
• IPM <mat_matrix> : This will create a general frame with a specific bilinear form matrix. The matrix is called the Inner Product Matrix (IPM) and must be square, symmetric, with constant elements, and having a number of rows\columns equal to the number of basis vectors of the frame. The given <mat_matrix>  is any Mathematica expression that results in a legal IPM.
• CBM <base_frame> <mat_matrix> : This will create a frame based on another base frame using a Change-of-Basis Matrix (CBM). <base_frame>  is the name of the base frame and <mat_matrix>  is any Mathematica expression resulting in a legal square CBM with constant elements. The base frame must have the same number of basis vectors as the new frame and number the CBM rows\columns.
• reciprocal <base_frame> : This will create a frame based on another base frame using a Change-of-Basis Matrix (CBM). The new frame will be the reciprocal of the base frame and the CBM is automatically computed. Both frames must have the same number of basis vectors.

4.3. Subspaces

A Subspace of a frame can be defined using:

subspace <name> = @ <basis_blades> @

• <name>  is the name of the subspace inside the frame
• <basis_blades>  is a comma-separated list of basis blades that the subspace will span.

Each element of <basis_blades>  can be any of the following:

• The name of a basis blade of the frame (in any form: canonical, indexed, or binary indexed).
• ga{ <basis_vectors> }  where <basis_vectors>  is a set of basis vectors of the frame. This form specifies a sub-geometric algebra based on the selected basis vectors of the frame.
• A name of another subspace already defined for the frame.

When a frame is defined, GMac automatically creates several default subspaces each spanning k-vectors of some grade k. These subspaces are named G<k>  where <k>  is any number between zero and n, the dimension of the frame (the number of its basis vectors). This form specifies all basis blades of grade k and can be used as any user-defined subspaces.

4.4. Frame Default Code Items

When we define a frame GMac automatically defines several useful child code items. You can inspect these items by compiling a frame and showing its sub-items inside GMacIDE. Here is a list of some of the default items:

• The default multivector type called Multivector . We will talk about GMacDSL’s types shortly.
• Some default constants named E0 , E1 , E2 , etc. holding multivector values of the 2^{n} basis blades of the frame. In addition to the default constant I  holding the frame’s pseudoscalar multivector value.
• Some default subspaces like G0 , G1 , G2 , etc. spanning k-vectors of different grades from 0 to n. In addition to the default subspaces pseudoscalars (the pseudo-scalars subspace of the frame), even (the even grade k-vectors of the frame), odd (the odd grade k-vectors of the frame), and ga (the full GA space of the frame).
• Some default structures used to compute outermorphisms and general multivector linear transforms. See the GMac Guide for more details.
• Many default macros to perform common useful operations on the frame’s multivector values useful during code generation from GMac. See the GMac Guide for more details.

---

5. Types

A type defines a grouping of scalar values into a combinatorial tree of fixed form. Types can be any of the following three kinds:

• In GMacDSL there is one built-in data type called scalar used to represent real numbers. This is a simple type with a single scalar value. The combinatorial tree of a scalar type is a single node.
• When any frame is defined GMac automatically creates a Multivector type for that frame. If the frame has n basis vectors the Multivector type is a combination of 2^{n} scalar values that correspond to the scalar coefficients of the basis blades of the frame. The combinatorial tree of a Multivector type is a root node with 2^{n} leaf scalar nodes.
• Any GMacDSL structure is also a type. The combinatorial tree of a structure type can be of arbitrary form with leaf scalar values. We will discuss Structures later on.

---

6. Constants

In GMacDSL a Constant can be defined inside a namespace or a frame using:

constant <qname> = <expr>

• <qname>  is the qualified name of the constant.
• <expr>  is a GMacDSL expression.

The expression will be evaluated at compile time into a constant value and the value will be automatically substituted whenever the constant‘s name is used as part of any following expression. The type of the new constant is automatically determined as the expression’s type.

In addition to user-defined constants, each frame basis vector is associated with a constant value of type Multivector. These basis vector constants can be used inside expressions exactly like user-defined constants; they are read-only data-stores that are assigned their constant values at compile time.

---

7. Structures

In GMacDSL a Structure is a combinatorial type that can be defined inside a namespace or a frame using:

structure <qname> (<members>)

• <qname> is qualified name of the structure.
• <members>  is a comma separated list of data members definitions.

The members list can contain one or more data member definitions. Each data member is defined as <name> : <type>  where <name>  is the name of the member and <type>  is its type.

GMacDSL structures are not recursive. A data member of structure S  cannot be of type S . In addition, a data member can only be defined using types already defined in previous code not in following code.

Because a data member of a structure can be of a type that is itself another structure, structures can be used to create non-recursive combinatorial trees having leafs of scalar values to represent more complex geometric concepts that a single multivector can’t typically represent; then we can use macros to define GA operations on these structure values. We already showed an example when we talked about GMacDSL types.

---

8. Macros

In GMacDSL a Macro is an abstraction of a geometric algebra computation that can be defined inside a namespace or a frame using:

macro <qname> (<parameters>) : <out_type> begin <commands> end

• <qname> is the qualified name of the macro
• <parameters>  is a comma separated list of macro parameter definitions. The list can contain one or more parameter definitions; each parameter is defined as <name> : <type>  where <name>  is the name of the parameter and <type>  is its type.
• <out_type>  is the type of the value returned by the macro.
• <commands>  is a list of GMacDSL commands to be executed when the macro is called or used for a GA computation. We will talk about commands and expressions in full details shortly.

In addition to user defined macros there are several useful built-in GMacDSL macros:

• reverse: The Reverse of a multivector.
• grade_inv: The Grade Involution of a multivector.
• cliff_conj: The Clifford Conjugate of a multivector.
• norm2: The squared norm of a multivector. This operation is metric dependent (i.e. it depends on the bilinear form of the frame) and can result in negative scalars having no real root for some frames.
• mag2 : The squared magnitude of a multivector. This operation is metric dependent and will always result in positive scalars.
• mag : The magnitude of a multivector. This operation is metric dependent and will always result in positive scalars computed from the positive square root of mag2.
• emag2 : Same as mag2 and norm2 but assumes a Euclidean metric for the multivector.
• emag : Same as mag and the square root of emag2 but assumes a Euclidean metric for the multivector.

---

9. Macro Templates

In many cases we need to define the same macro under several frames. For example a macro to create the inverse of a versor is common in geometric algebra. Instead of manually duplicating the same macro definition inside several frames we can use a macro template and implement the template in any frames we need easily. The general syntax for a macro template is exactly like that of a macro but prefixed by the template keyword:

template macro <qname> (<parameters>) : <out_type> begin <commands> end

Then we can implement the template using:

implement <qname_list> using <frames_list>

• <qname_list>  is a comma separated list of qualified macro templates names to be implemented.
• <frames_list>  a comma separated list of qualified frame names where the macros will be created.

---

10. Commands

Inside GMacDSL macros, a command represents the smallest abstract high-level unit of execution. There are few simple commands in GMacDSL:

• The declare command.
• The let command.
• The return command.

These commands are always inside a command block between the begin\ end keywords. Command blocks can be nested like the case in C++ and other similar languages.

10.1. The declare Command

The declare  command is used to declare local variables inside a command block:

declare <var> : <type>

• <var>  is the name of the local variable.
• <type>  is the type of the local variable.

No two local variables in the same command block can have the same name, but we can declare a variable with the same name inside child command blocks. When a new local variable is created all of it’s leaf components are set to zero. So if we use the variable or any part of it in a following expression before assigning a value to it we will get zeros from the part we read. More about full and partial local variable access later on.

10.2. The let Command

The let command has 3 forms:

let <var> : <type> = <expr>

let <var> = <expr>

let <part_var> = <expr>

• <var>  is the name of a local variable
• <type>  is the type of the local variable
• <expr>  is a right-hand-side GMacDSL expression
• <part_var>  is a partial access of a local variable. We will talk about expressions and partial access in GMacDSL shortly.

1. The first form let <var> : <type> = <expr> can be used to declare a new local variable inside a command block and assign an expression to it. The name must be unique within the command block and not used before in any declare or let commands of the same command block.
2. The second form let <var> = <expr>  can be used to assign an expression to a local variable. If the local variable is found in this command block or any parent command block its value is changed. If no such variable is found a new local variable is declared and assigned the expression.
3. The third form let let <part_var> = <expr>  is used to change a part of a compound local variable that is already declared. A compound local variable is a variable of type multivector or structure, not a scalar.

When assigning an expression to a variable or part of a variable the types must be compatible. We can assign a scalar expression to any multivector or scalar variable. We can assign a multivector expression to a variable of the same multivector type. We can assign a structure expression to a variable of the same structure type. All other possibilities are not allowed and all assignments in GMac are strictly by value; there are no references or pointers in GMacDSL like some other languages have.

10.3. The return Command

The return command is used to assign a value to the return variable of a macro:

return <expr>

Where <expr>  is an expression assigned to the macro’s return variable.

This command can only be used inside a command block if it’s part of a macro definition; it can’t be used, for example, inside a composite expression used to define a constant.

When any macro is defined, GMac automatically adds a hidden output parameter named result as the first parameter of the macro. The parameter result has the same type as the return type of the macro. When we add a return command we are just assigning the expression to the result parameter. The return command does not stop execution of any following commands, it just alters the value of the result macro output parameter. Normally the return command should be the last in the macro’s command block. The return <expr> command is semantically equivalent to let result = <expr> so the type of the expression must be assignable to the type of the output result parameter as we discussed in the let command.

---

11. Expressions

GMacDSL expressions are the reason behind the power of this simple GA-based DSL. Many GA operations are supported and are easy to use as we will see shortly. Expressions are used to define constants in addition to let and return commands. There are several types of GMacDSL expressions:

1. Constant number value.
2. Full and Partial data-store access.
3. Symbolic scalar.
4. GA arithmetic.
5. Constructor.
6. Macro call.
7. Composite.

11.1. Constant Number Value

A constant number value is simply a normal integer or floating point number like: -1 , 10.345 , or -12.2345e-9.

11.2. Full and Partial Data-Store Access

A data-store in GMacDSL is either a constant, macro parameter, or local variable. They’re called data-stores because they can be used to store data (i.e. values) either at compile time (a constant), or at computation time (a macro parameter and a local variable). In GMacDSL we can access (i.e. read\write) the full value of a data-store or any part of it. Constants are always read-only, but macro parameters and local variables are read-write. Initialization of data-stores goes as follows:

• The initial value of a constant is determined inside its definition at compile time. This value is never changed after that.
• The initial value of a local variable is a combinatorial tree of zero leaf values if the variable is created using a declare command, and is a user-defined value if initialized using a let command. That value can change using later let commands inside the same command block or any child command block.
• The initial value of a macro parameter is determined from the calling macro and can change inside the called macro’s command block or any of its child command blocks. If we change the value of a macro parameter the calling macro will not be affected as all parameter assignments in GMacDSL macro calls are by value not by reference.

11.3. Symbolic Scalar Expression

A symbolic scalar expression is a string that can be evaluated by Mathematica to produce a scalar value. For example:
‘-1’ ‘2 * Pi’ ‘Sin[Rational[3, 4] * Pi]’

One important feature of symbolic scalar expressions is that they can be parametric. For example the expression ‘Sin[$d$]’  is interpreted as “read the value of d  and create a Mathematica expression that is the Sin[]  of that value”. d  can be a constant, parameter, or local variable of type scalar. Actually any legal GMacDSL expression of type scalar can be put inside the $ $ delimiters in a symbolic scalar expression. This is a form of small inline macro call in GMacDSL. The resulting type of a symbolic scalar expression is assumed by GMac to be of type scalar. In this way many powerful symbolic computations can be performed with GMacDSL using Mathematica.

11.4. GA Arithmetic Expression

GMacDSL supports many GA arithmetic operations on scalar and multivector values:

• Unary negation of a scalar or multivector value (ex. -x).
• + \ -  (binary addition and subtraction operators): These can be applied to two scalars, two multivectors of the same frame, or a scalar and a multivector.
• *  (binary times operator): This can be applied to any two scalars, or a scalar and a multivector.
• /  (binary divide operator): This can be applied to any two scalars, or to a multivector and a scalar; the multivector must come first in this case.
• GA bilinear products: These can be applied to two multivectors of the same frame, or to a scalar and a multivector. They generally return a multivector except for the scalar product sp and Euclidean scalar product esp operators that return a scalar.

11.5. Constructor Expression

In GMacDSL we can directly create a multivector or a structure value by specifying the components of the multivector or structure. This operation is similar to object initialization in OOP languages.

To construct a multivector value we use one of the following:

<qname> ( <coef_list> )

<qname> ( <scalar_expr> )

<qname> { <init_expr> } ( <coef_list> )

• <qname> is the name of the multivector type
• <coef_list> is a comma separated list that assigns an expression to coefficients of basis blades in the created multivector value
• <scalar_expr> is a single expression of type scalar.
• <init_expr> is an expression for initializing the multivector value before the coefficients are assigned using the <coef_list>.

The second form can be used to cast a scalar into the Multivector type of some frame.

We can also use a subspace to create a multivector value using one of the following:

<qname> ( <expr_list> )

<qname> { <init_expr> } ( <expr_list> )

• <qname> is the qualified name of the subspace.
• <expr_list> is a comma separated list of scalar expressions. Each expression is assigned to a basis blade coefficient for a corresponding basis blade in the subspace. The basis blades are ordered by their ID as in their indexed name E<n>
• <init_expr> is an expression for initializing the multivector value before the coefficients are assigned using the <coef_expr>.

To construct a structure value we use one of the following:

<qname> ( <member_list> )

<qname> ( <expr_list> )

<qname> { <init_expr> } ( <member_list> )

<qname> { <init_expr> } ( <expr_list> )

• <qname>  is the name of the structure type.
• <member_list>  is a comma separated list that assigns an expression to members of the created structure value. We can use full or partial data-store access on the members. This form is very useful for readability especially when only a small number of members are to be initialized. No specific order of members is needed here.
• <expr_list>  is a comma separated list of expressions. Each expression is automatically assigned to a full structure member according to the order of the member’s declaration inside the structure. This form is useful when most of the members are to be fully initialized.
• <init_expr>  is an expression for initializing the structure value before the members are assigned using the <member_list>

11.6. Macro Call Expression

To call a macro, that is already defined, we use one of the following:

<qname> ( <param_list> )

<qname> ( <expr_list> )

• <qname>  is the name of the macro.
• <param_list>  is a comma separated list that assigns a expressions to parameters of the called macro. We can use full or partial data-store access on the parameters.
• <param_list>  is a comma separated list that assigns a expressions to parameters of the called macro. We can use full or partial data-store access on the parameters.

All values are assigned to parameters of the called macro by value so that is the called macro changes the value of its parameter it will not affect the calling macro.

In GMacDSL macros are not recursive. We can never call a macro from itself or call a macro that will be defined in following code.

11.7. Composite Expression

A composite expression is command block that has a return value and starts with a declaration of its final output local variable. This is somehow conceptually similar to an inline macro with no parameters. The general form of composite expressions is:

{ output <var> : <type> <commands> }

• <var> is the name of the local variable that will contain the final value of the composite expression. This variable is called the composite expression’s output variable.
• <type> is the type of the output variable.
• <commands> is a list of GMacDSL commands that will eventually change the value of the output variable.

---

12. Identifier Referencing Rules

In GMacDSL, namespaces, frames, macros, structures, command blocks, and composite expressions have scopes. A scope is a “personal” code space where child code items can be defined. For example:

• Inside a namespace’s scope we can define child namespaces, frames, structures, macros, and constants.
• Inside a frame’s scope we can define basis vectors, subspaces, the Multivector type of the frame, constants, structures, and macros.
• Inside a macro’s scope we define macro parameters and a single command block that itself has a scope.
• Inside a structure’s scope we define data members.
• Inside a command block or a composite expression we can define other command blocks, composite expressions, and local variables.

In order to use a code item from any scope in GMacDSL we can always use a “full qualification” of the item’s name. Full qualification is accurate but tedious to write. An alternative is by using referencing rules that simplify using code items from other scopes in the code. Instead of explicitly stating the rules we will give examples to show how referencing code items works in GMacDSL.

when defining or activating a namespace (like the main, conformal, or twist namespaces) we must use full qualification:

We can define a child code item under the active namespace easily. For example:

This will define the e3d frame under the main namespace and the ApplyTwist macro under the main.conformal.twist namespace.

If we need to add a child code item under a frame (i.e. a constant, structure, or macro) we have to use relative referencing to reach the frame from the current scope. For example to define the Line structure after activating the twist namespace:

Or we can activate the main namespace and use simpler code:

The other kind of referencing we need to understand happens during resolving identifiers for types and other identifiers inside expressions. We usually need this type of referencing when:

• Selecting the type of a structure data member, a macro parameter, or a local variable inside a command block.
• Reading the value of a constant inside an expression.
• Constructing a multivector or a structure.
• Calling a macro from inside an expression.

When defining the Line structure we automatically enter its scope to define its members. We can use relative referencing to select the types of its members here as follows:

We can use Multivector instead of e3d.Multivector because the scope of Line (the active scope) is inside the scope of e3d and GMac searches the scope tree from the active scope upwards.

Compare this to defining the twist structure:

We had to use full qualification because the active scope of main.conformal.twist.Twist is too far from the multivector type we need to use main.e3d.Multivector.

To make it more easy to reference that type we can use the open keyword as follows:

Here GMac will not find Multivector as an identifier inside the active scope or its parents; it will then search the opened scopes and their parents until it finds an identifier with the given name. Note that whenever GMacDSL finds a namespace activation it automatically clears all opened scopes.

Assuming the cga5d frame has basis vectors no, e1, e2, e3, and ni we can use their names as constant multivector values inside any expression in our code, we just need to reference them correctly. Assuming we need the outer product of no and e1 inside the ApplyTwist macro, one way is to use the full qualification of their frame:

let x = main.cga5d.no ^ main.cga5d.e1

This method is hard to write and read especially when we need an expression depending on many constants or macros defined under a far away frame.

Another alternative is to use the “temporary open frame scope” operation <frame>.& & :

let x = main.cga5d.& no^e1 &

This operation temporarily adds the frame’s scope as the top opened scope. When GMac searches the active scope and does not find the no identifier it automatically searches the opened scopes and their ancestors one by one. Since main.cga5d is the top opened scope it will find that no is a constant and get its value. The same will happen with e1 and after that the main.cga5d scope will be removed from the top of the opened scopes. Note that even if main.cga5d is already opened using the open keyword it will only be searched once.