joemat-interface

A MATLAB interface to the Joe-s-Special-Matrix-Calc library.

Note: In this document, .* stands in for one of the shared library extensions .dll (Windows), .so (Linux), or .dylib (macOS).

Building

1. Run the following commands by copying each line and runing them (one at a time):

git clone https://github.com/cherche/joemat-interface.git
cd joemat-interface/
make clean
make shared

This should produce a library file libjoemat.* in bin/.

2. Next, open MATLAB, navigate to the project directory, and run generateInterfaceDefinition.m. This should produce two files definejoemat.m and joematData.xml.

3. Finally, run build(definejoemat) to produce another library file joematInterface.* (the interface) in joemat/.

Installing

Simple single-project installation

As an example, here is how one might install this library and its interface to a MATLAB project located at project/. Place libjoemat.* and joematInterface.* as in the following directory structure:

project/
│
└───bin/
│   │   libjoemat.*
│
└───joemat/
    │   joematInterface.*

Then place all the files in mlfunctions/ in the root project directory project/, or simply add mlfunctions/ to the MATLAB path.

Technical installation

1. Ensure that the library file libjoemat.* is either somewhere in your system's run-time library path, or in bin/ within your working MATLAB directory. (Your working MATLAB direcotory is the project folder that is open when you are running code that uses the interface.)
2. Ensure joematInterface.* is in one of the directories in the MATLAB path. To do this temporarily, run the command

addPath("path/to/joemat-interface/joemat")

Alternatively, set the path from the GUI.

3. Similarly, ensure mlfunctions/ is in the MATLAB path.

Usage

Fix a dimension n and let matrixSeq be the type corresponding to the horizontal MATLAB arrays consisting of n-by-n MATLAB matrices. The following four functions are available:

• getLieAlgebraBasis(matrixSeq generators) -> matrixSeq
• getLieAlgebraDim(matrixSeq generators) -> int
• getLieAlgebraCentralizer(matrixSeq generators) -> matrixSeq
• getLieAlgebraNormalizer(matrixSeq generators) -> matrixSeq

In each case above, generators is a collection of generators for the Lie algebra for which one wishes to compute the relevant invariant, e.g., getLieAlgebraBasis will return a basis for the algebra generated by generators, and getLieAlgebraNormalizer will return a basis for the normalizer of the algebra generated by generators.

Usage of interface from MATLAB (without mlfunctions/)

Technically speaking, the functionality described above is an abstraction supplied by the functions in mlfunctions/. One can equally directly call functions supplied by interface to the C++ library, wherein the inputs and outputs are string representations of the corresponding objects. Such a paradigm may be preferable when the final output is to be a string, so that string–MATLAB object conversion is not done unnecessarily.

String representations

One must first understand how information is passed between MATLAB and C++. In fact, the interface almost entirely handles string representations of sequences of matrices (or sequences of bases of Lie algebras, in the case of series). This representation must satisfy the following to be processed correctly:

• each matrix must be surrounded by a pair of square brackets ("[" and "]");
• a semicolon (";") separates every two rows of the same matrix;
• a space (" ") separates every two elements of the same row;
• a newline ("\n" in C++ or newline in MATLAB) separates every two matrices in the basis for the same Lie algebra;
• an at-symbol on its own line ("\n@\n" in C++ or newline + "@" + newline in MATLAB) separates every two bases, i.e., separates Lie algebras from one another;
• and there are no additional characters (including whitespace).

Here's a correct string representation of the standard basis for gl(2,ℂ), followed by the standard basis for sl(2,ℂ):

[1 0;0 0]
[0 1;0 0]
[0 0;1 0]
[0 0;0 1]
@
[0 1;0 0]
[0 0;1 0]
[1 0;0 -1]

Here's an incorrect string representation of the same pair of bases:

[1 0; 0 0]
[0 1;0 0]

[0 0;1 0]
[0 0;0 1]
@

[0 1;0 0]
[0 0;1 0]
[1 0;0 -1]

Functionality available in the interface

The following four functions are available:

• clib.joemat.getLieAlgebraBasis(str) -> str
• clib.joemat.getLieAlgebraDim(str) -> num
• clib.joemat.getLieAlgebraCentralizer(str) -> str
• clib.joemat.getLieAlgebraNormalizer(str) -> str

Below is an example which determines the size of the centralizer and also prints out a basis.

# Start with a given matrix sequence of generators
# (i.e., a MATLAB array of matrices):
#
# generators = [...]

# First, convert to a string usable by `clib.joemat`
generatorsString = matrixSeqToString(generators)

# Get a string representation of the centralizer
centString = clib.joemat.getLieAlgebraCentralizer(generatorsString)

# Get a MATLAB array (a "matrix sequence") representing a basis
# of the centralizer in order to determine the dimension of the centralizer.
# Note: This is only for the sake of demonstration.
# Practically, it is faster to count opening brackets [ in the string representation.
cent = stringToMatrixSeq(centString)
centDim = length(cent)

Direct usage of C++ library (using compat.h)

The library works with GiNaC objects, mostly matrices. It also introduces a type lie_algebra* with corresponding methods. One can simply enter GiNaC matrices in C++, compile, and run the compiled program. For users' convenience, we also supply compat.h which contains methods which translate matrices, matrix sequences, and sequences of matrix sequences (informally "sequences of Lie Algebras") to and from their string representations (see above).