1. GMac System Overview

1.1. Download and Installation

GMac was originally created using C# 4.0 under Visual Studio (VS) for .NET framework 4. You can download the latest version of GMac from here. After you extract the GMac files you can open the GMac.sln file, or build and add GMac.exe, as a component library, to your Visual Studio .NET project to take advantage of its processing capabilities fully detailed in the GMac Guides.

1.2. What You Need to Know

If you’re interested in GMac you probably have some concerns in one of the following general knowledge domains. In all these cases, you will find GMac a useful tool to have:

• You are using Geometric Algebra (GA) in your work and need to explore and implement GA models and algorithms for prototyping purposes. You may also have an interest in implementing your GA-based algorithms in a computationally efficient manner in a programming language of your choice, like C++, Java, Python, C#, VB, etc.
• You are performing tasks requiring Geometric Computing at their core, like robotics simulators, graphics\physics engine design, modeling and simulation of mechanical systems, computational geometry, interactive geometry software systems, etc.
• You are a software engineer exploring code generation techniques for implementing scientific computing software systems.

To use GMac, you naturally need to understand the basics of Geometric Algebra and how to use it to model and process geometric data. You can find many GA-related online resources, books, and even other GA-related software in the GA Resources page on this site. In its current version, GMac relies on Wolfram Mathematica for symbolic manipulations in the background. So you need to have some idea about Mathematica’s Wolfram Language and symbolic manipulation capabilities. If you only intend to use GMac as a GA calculator you need to learn the simple yet effective GMacDSL and GMac Scripting languages, in addition to the main structure of the GMacAST. On the other hand, if you want to fully use GMac’s code composition capabilities, its main reason for being, you need to be a software developer with good .NET background and, in addition to the previous requirements, you also have to carefully study the TextComposerLib and GMacAPI used for code composition from GMacAST structures compiled from GMacDSL code.

1.3. GMac and Wolfram Mathematica

The idea behind GMac is to transform high-level GA-based sequences of computations into low-level coordinate manipulation computations on sparse multivectors. GA algorithms by nature are compact and general with high geometric significance, in contrast with other mathematical tools like vector algebra and matrices. On the other hand, computers need detailed low-level instructions on how to produce outputs from the inputs for specific tasks. GMac fills this gap by compiling the GMacDSL code into GMacAST structures, then generating structured low-level computational code based on the information in the GMacAST. For this process to be done GMac needs a Computer Algebra System like Mathematica in the background to perform basic symbolic manipulations guided by the GA main rules of computation with GA multivectors. In the future, other computer algebra systems, especially open-source systems like SageMath and SymPy, would be used for the same task that Mathematica does to make GMac more flexible and accessible by a wider range of users.

The communication between GMac and Mathematica is through the. NET/Link API that comes with Mathematica installations. Any version of Mathematica 7.0 or later can work with GMac after adding required Mathematica .NET/Link DLLs to the folder containing the GMac.exe file. These DLLs are:

1. The .NET/Link API’s file, called Wolfram.NETLink.dll, can be found under the <Mathematica Install Folder>\SystemFiles\Links\NETLink\ folder. For example, if you are using Mathematica 11 the full path of this DLL is by default: C:\Program Files\Wolfram Research\Mathematica\11.0\SystemFiles\Links\NETLink\Wolfram.NETLink.dll
2. For Mathematica 10 and later, two additional DLLs under the same folder are also needed: ml32i4.dll  and ml64i4.dll. These files were used to be installed in the Windows System folder but now are just kept under the main .NET\Link folder so we need to copy them manually to the GMac folder.

If you create a .NET project that uses GMac, you typically would add a reference to the Wolfram.NETLink.dll file. As described in the Mathematica documentation, programs that use .NET/Link need to have a reference to the Wolfram.NETLink.dll assembly in their project settings. You add a reference to an assembly by selecting Add Reference from the Project menu in Visual Studio. The Wolfram System installer makes the necessary settings so that the Wolfram.NETLink.dll assembly shows up in the Add Reference dialog box. If for some reason it does not show up there, you can simply use the Browse button to locate the file manually; it should be in the <Mathematica dir>\SystemFiles\Links\NETLink directory. When Visual Studio .NET builds your project, it will automatically place a copy of Wolfram.NETLink.dll in the output directory, alongside your .exe file. Your program will require a copy of Wolfram.NETLink.dll alongside it to run, so if you deploy your program to another location or distribute it to other users, you must keep the Wolfram.NETLink.dll file with it.

---

2. GMac Solution Projects

Internally, GMac is composed of the following shown projects. The diagram shows the dependency of the projects on each other. Now we explain briefly the purpose of each project in the overall system.

2.1. The TextComposerLib Project

This project is a complete independent library for structured text composition. The full capabilities of this library are explained in the TextComposerLib Guide. Most of the other projects depend on this library in some way. This basic library can be used outside GMac for structured text generation tasks or arbitrary nature.

2.2. The UtilLib Project

This project is a general helper utility library containing some useful data structures frequently used by the other projects in the GMac solution. I will not go into the details of this library because they are irrelevant to the exposed GMac software and user interfaces.

2.3. The SymbolicInterface Project

This project contains an intermediate wrapper around Wolfram Mathematica’s .NET/Link API. The symbolic computations of GMac use this project’s classes extensively. The SymbolicInterface project is useful on its own for communicating with Mathematica in an OOP organized manner. More information about can be found in the GMac Math Guide.

2.4. The IronyGrammars Project

GMacDSL is a Geometric Algebra-based domain-specific language implemented using the Irony .NET Language Implementation Kit library. Based on Irony we can implement many language applications like parsers, syntax highlighters, code analysis tools, DSLs, etc. The IronyGrammars project is a collection of classes that are useful in designing such Irony-based language applications. The details of this project are hidden by the GMac Compiler software interface.

2.5. The GMac Project

This is the main project of the GMac system. At the beginning, you don’t need to understand in details all the classes in this project. But as you gain more experience with GMac, in the direction of generating code libraries, you will eventually need a solid understanding of the classes in this project, especially the GMacAPI classes. You may also find the classes design useful from a pure software engineering point of view as a case study on practical DSL design and implementation. The main namespaces under the GMac project are:

• GMac.GMacCompiler : This namespace contains classes used in compiling GMacDSL code into GMacAST structures. The detailed knowledge of these classes is not required for using GMac. Only the public interface of a small set of classes is useful during code generation from GMac.
• GMac.GMacAST : The classes under this namespace contain the main information abstracted from GMacDSL code. The GMacAST structures are the primary source of information for both scripting and code generation activities in GMac. The full details of the public interface of these classes are explained in the GMacAST Guide.
• GMac.GMacUtils : This namespace contains many useful computational utilities and extension methods used by GMac. The utilities are useful by themselves, however, for general GA-based computations. A full explanation of these utilities is in the GMac Math Guide.
• GMac.GMacScripting : The classes comprising the GMac Scripting Engine are under this namespace. The scripting engine is accessible through the GMacIDE, so there is no need to study these classes. However, they provide a good example of designing an effective scripting engine for arbitrary purposes.
• GMac.GMacAPI : This is the most important, and indeed the largest, namespace in the GMac system. Here we find all classes useful in creating structured code for arbitrary target programming languages from GMacAST information. The correct usage of this important namespace can be found in the GMacAPI Guide.
• GMac.GMacIDE : This namespace contains the GMac User Interface. Many operations related to GMacDSL creation and compilation, GMacAST exploration, GMac scripting, and sample code generation from GMac macros can be accessed from the simple GMacIDE. The full details of the GMacIDE are described below in the third section of this guide.

---

3. The GMac Interface

GMacIDE is a simple Integrated Development Environment for users to interact with GMac. To start the GMacIDE simply run GMac.exe and the interface starts. The GMac splash screen should appear showing GMac initialization steps. The first time you run GMac it will take some time to create and save initialization files including internal lookup tables for GA computations. The file GMacSettings.xml can be used to set the maximum number of dimensions, between 6 and 15, for GMac computations. If the Mathematica DLLs are installed correctly GMac will start an instance of the Mathematica Kernel in the background and the main interface will be shown next.

If all goes well, the GMacIDE main screen appears next. The menu toolbar of the screen contains the following items:

• File
  • New Project
  • Open Project
  • Manage Source Files
  • Edit Source File
  • Save Source File
  • Close Source File
  • Exit
• Compile
  • Compile GMacDSL Code
  • Compiler Options
• Tools
  • Code Generator
  • Explore GMacAST
  • Explore Macro
  • Interactive Script
  • Explore Loaded .NET Assemblies
• Help
  • About GMac

We will now show how to interact with GMac through the GMacIDE and its main menus.

3.1. Managing GMacDSL Projects

The first thing we can do is to create a new GMacIDE project or open an existing one from the File menu. In either case, a dialog is shown to save or select the project file having a .gmacproj extension. After the project saveing\selection dialog returns, we can manage the GMacDSL code files of the project by selecting the Manage Source Files menu item under the File menu.

This menu item shows a simple screen where we can add, remove, and reorder GMacDSL source code files in our project. The screen is currently a very simple text box where we can directly manipulate its lines containing the full paths of the project’s files.

The order of the GMacDSL source files is important in GMac because the GMac compiler concatenates the text in the files in their order to create a single contiguous code string that gets compiled into a GMacAST structure. You can write all your code in a single file. You can also separate your code into multiple files for modularity purposes. Perhaps grouping the code for each GA frame in its file or separating the definition of frames, structures, and macros into separate files. There is no restriction on the structure of the files as long as it’s syntactically and semantically correct after being concatenated by GMac into a single string.

At any point, you can open a single GMacDSL code file for reading and editing in the GMacIDE. You can either double-click the file name in the Source Files tab at the right of the screen or select the file and select Edit Source File from the File menu. You can save and close the opened GMacDSL code file from the corresponding items in the File menu.

3.2. Compiling GMacDSL Code

After you finish the GMacDSL code in the project files, you can compile the project into an in-memory GMacAST structure. The GMacAST structure is temporary and cannot be saved to disk for later use, so you have to compile the GMacDSL code each time you need to use it. This is not a problem because GMac Compiler is fast and GMacDSL code is compact and simple, in contrast with general purpose programming languages. To compile the code you can press Control+F5 or select the Compile GMacDSL Code menu item under the Compile menu.

At the bottom of the GMacIDE screen, you find 3 tabs: The Output, Errors, and Warnings tabs. If the compilation is successful, no messages are displayed in the Errors tab and a tree listing of the compiled components, like frames, structures, and macros are shown on the right in the Components tab. You can double click on any component to open the code that created it in the code editor. If the component is created from code written by the user the code can be edited normally. If the component is automatically generated by the GMac Compiler, like many macros attached to GA frames, the code is shown in read-only mode in the editor.

If the code contains errors, compilation fails and the error messages are displayed in the Errors tab. Now you can select an error message and the corresponding code will be shown and highlighted in the code editor so you can fix and compile again.

You can control some aspects of the compilation and the symbolic optimization process from the Compiler Options screen by selecting the Compiler Options menu item. Each option has a certain effect on compilation described at the bottom of the screen. For example, some options reduce symbolic optimization time by allowing for less than optimal symbolic expressions.

3.3. Exploring GMacASTs

The details of the compiled GMacAST can be investigated using the Explore GMacAST menu item under the Tools menu. In this screen, you can double-click on any item in the tree on the left to display a full-text description of the item.

You can also select to show a diagram related to the item from the Diagrams menu. The diagrams are created as GraphViz code that is displayed in the GraphViz rendering window:

 

3.4. Exploring A GMac Macro

In the main GMacIDE screen, you can compile your code and select any macro from the Components tab on the right. Now if you select Explore Macro under the Tools menu, the explore macro screen appears. This screen can be used to generate sample code from the selected macro after selecting which macro parameters are kept as variables, set to given constants, or equal to zero. This process gives many details on how GMac generates code from macros.

At the top left you can find the name of the selected macro and the full list of input and output parameters, fully expanded to their scalar components. In this list, you can remove any parameter components you need to fix at zero. You can also add “= <constant>” at the end of any line to assign a constant scalar value to a specific parameter component. Any other component in the list is assumed to be a variable. You can restore the original list using the Reset Parameters button at the lower left of the screen. Now if you press the Generate button, GMac starts processing the macro, taking some time depending on the complexity of the macro and the selected compiler options. After generation completes the list on the right displays a full trace of the internal steps of macro generation. You can now explore the result of each step as you like.

You can also press the GraphViz button so that GMac generates GraphViz code based on the generated computations of the macro. The GraphViz code is shown in the GraphViz screen that contains an interface for producing graph diagrams based on the given code.

The graph gives a rough idea of the complexity of the coordinate-based computations required to implement the macro with the selected parameter bindings. A summary of the amount of computations, memory reads, used variables, etc. is shown in the graph. The graph is color coded to show the propagation of information from input to output parameter components taking into account the number of computations needed at any stage.

 

3.5. Scripting with GMac

One very important task for the GMacIDE is to allow for the user to create simple GA-based scripts in GMac and investigate the results. The Interactive Script menu item under the Tools menu shows the scripting UI window. Here you can write GMac scripts, described in details in the GMac Scripting Guide, to explore your GA model without generating any code. In the scripting window you can interact with the symbolic engine, Mathematica, the GMacAST, execute arbitrary GMacDSL expressions on multivectors, and access .NET assemblies loaded in memory with the GMac process. You can see these .NET assemblies using the Explore Loaded .NET Assemblies menu item under the Tools menu. The scripting language is essentially C# with some syntactic sugar, so the combination is powerful enough for many computational tasks.

You can write, or load, your script in the Script tab then press F5 to execute the script. Internally the script is translated into a normal C# class and the script is put in a method of that class called Process(). You can create more members and methods to be added to the generated script class in the Members tab.

You can see the full code of the generated C# script class in the C# Code tab as shown here.

The Namespaces tab contains a list of all Namespaces in the .NET assemblies loaded in memory with GMac. You can add or remove any namespaces to be used in the generated script class. Some namespaces cannot be removed because they are fixed as a minimum in the generated class.

At the lower part of the screen, we find three tabs: the Output, Commands, and Errors tabs. If all goes well, the Errors tab will contain no messages and the Output tab will contain any string messages printed from the script as the user wrote. The Commands tab contains a listing of all GMac commands executed by the script.

If you press Control+P or select Progress Log from the View menu, the Progress window opens showing a detailed log of all steps taken to execute the script. This is very useful to identify errors and see execution time of various parts of the script.

 

---

4. GMac as a Library for Code Composition

The GMacIDE is useful for simple explorations of GA algorithms, but the full power of GMac comes from its core library and the GMacAPI classes. To take advantage of this GMac component, you typically need to create a .NET solution in any .NET language of choice (C#, C++, VB, F#, IronPython, etc.). You also need to add a reference to the GMac.exe file in your project to access its internal classes. The full details of creating a code generation solution in this way are described in the GMacAPI Guide. Several sample projects to explore this capability (will be uploaded soon) can be found in the GMac Samples page on this site.