Group file format

This page documents the current format of .group files. Many disclaimers apply.

This format may change, and if you create .group files according to it, you will need to change them, too. (If the format changes, of course, all the .group files that come with Group Explorer will be changed simultaneously. You would only be responsible for files you created yourself.)
The format is not necessarily consistent from one document entity to the next. Your patience is appreciated.
This documentation is intended as a reference for the experienced user who wishes to dabble in creating new groups. It is not meant to be easy to read or follow.

Note that I would like to have a group editor one day that will allow users to graphically create their own groups using any of the visualizers currently available in Group Explorer. This would mean that no one would need to learn the file format anymore. But that is a future project.

The best way to learn the file format is to inspect a file and explain it thoroughly. Here is a fully-documented copy of the file defining the Klein 4-group. A very basic familiarity with XML is assumed.

<!DOCTYPE groupexplorerml> <group>
All group files begin this way. The first line declares the XML document type, and the second line begins the only entity in the document, the group.
<name text="V_4"><mrow><msub><mi>V</mi><mn>4</mn></msub></mrow></name>
The name of the group is required, and it must be provided in two formats. First, a text format as an attribute of the name tag, and second as MathML enclosed within the name tag. A small subset of MathML is supported; I intend to either remove all MathML support and simply return to HTML, or to make all of MathML supported, but this is one of the future changes that this file format will undergo. The subset of MathML that is supported is the following tags: mo, mo, mn, mrow, mtext, mspace, msup, msub, and mfenced.
<definition text="&lt; a, b | a2=b2=1, ab=ba &gt;"> <mfenced open="<" close=">" separators=":"> <mrow><mi>a</mi><mo>,</mo><mi>b</mi></mrow> <mrow><msup><mi>a</mi><mn>2</mn></msup><mo>=</mo><msup><mi>b</mi><mn>2</mn></msup><mo>=</mo><mn>1</mn><mo>,</mo><mi>a</mi><mi>b</mi><mo>=</mo><mi>b</mi><mi>a</mi></mrow> </mfenced> </definition>
The definition of the group is the representation of the group in the format < generators | relations >. It is given by an XML entity called definition, with one attribute called text. The entity contains the MathML for the definition, and the text attribute contains the same information but in HTML instead. (See how inconsistent this is?) Furthermore, in order to be enclosed in an XML attribute, the HTML must be escaped, so that all ampersands become & and all < and > become < and >, respectively.
<phrase>Klein-4 group</phrase>
The phrase entity gives Group Explorer a nice English name for the group.
<notes>Another name for this group is "Vierergruppe."</notes>
The notes entity can be left with no content, but if you as a group author have comments to make about the group, you can put them there. You may feel free to use HTML (provided that it is escaped, as mentioned above) and not feel restricted as to length.
<author>Nathan Carter (ncarter@bentley.edu)</author>
The author should include your name and your email address, in case users have questions about your work.
<multtable> <row> 0 1 2 3</row> <row> 1 0 3 2</row> <row> 2 3 0 1</row> <row> 3 2 1 0</row> </multtable>
The multiplication table for the group defines the group relation completely, and is here encoded as a multtable entity. It must contain row entities, and each row entity must contain as many natural numbers as there are rows. The first row must be the first n natural numbers, and the leftmost column in the table must also be 0 1 ... n. Other than these restrictions, the multiplication table must simply satisfy the group axioms.

<generators list="2 1"/>

It is helpful to provide Group Explorer with the generators for your group. If you do not, it will find some itself, but they may not be the ones you would have picked. This is especially important in relationship to the next type of entity in the file.

<representation> <element text="e"><mi>e</mi></element> <element text="v"><mi>v</mi></element> <element text="h"><mi>h</mi></element> <element text="hv"><mi>hv</mi></element> </representation>

There can be as many representation entities in the file as you like, and all will be alternatives to users of Group Explorer. The first one you list is the default. The element entities inside the representation provided names for elements 0 1 ... n, in that order. Just as with the group name, the text is a plain-text representation of the element name, and the material inside the element tag is MathML.

<cayleydiagram> <name>Three-pointed star</name> <arrow>2</arrow> <arrow>1</arrow> <arrow>3</arrow> <point x="0.0" y="0.0" z="0.0"/> <point x="0.0" y="-0.5" z="0.866"/> <point x="0.0" y="-0.5" z="-0.866"/> <point x="0.0" y="1.0" z="0.0"/> </cayleydiagram>

You may include as many Cayley diagram definitions in your file as you like. If you include none, there will be no custom Cayley diagrams for your group, but this is common and expected; you should only provide custom Cayley diagrams if it is useful to do so. If you choose to, the format above is easy to follow.

The name is required, and will appear in menus for the user to choose this diagram.

The arrow entities list the arrows which will be drawn in the diagram by default (although users can add/remove them, of course). The numbers inside the arrow tags refer to the numbers in the multiplication table you used to define the group.

The points (given as floating-point x,y,z triples, each component in the range [-1,1]) are the locations of the Cayley diagram nodes in 3-space, corresponding to the elements of the group in order 0 1 ... n. If you want to make a planar Cayley diagram, you should ensure that one of the three coordinates is zero for all points, as in this example.

<symmetryobject name="Rectangle"> <operation element="2" degrees="180.0"><point x="0.0" y="0.0" z="1.0"/></operation> <operation element="1" degrees="180.0"><point x="0.0" y="1.0" z="0.0"/></operation> <sphere radius="0.1" color="#FF0000"><point x="0.0" y="1.0" z="0.5"/></sphere> <sphere radius="0.1" color="#7FFF00"><point x="0.0" y="-1.0" z="0.5"/></sphere> <sphere radius="0.1" color="#00FFFF"><point x="0.0" y="1.0" z="-0.5"/></sphere> <sphere radius="0.1" color="#8000FF"><point x="0.0" y="-1.0" z="-0.5"/></sphere> <path color="#000000"> <point x="0.0" y="1.0" z="-0.5"/> <point x="0.0" y="1.0" z="0.5"/> <point x="0.0" y="-1.0" z="0.5"/> <point x="0.0" y="-1.0" z="-0.5"/> <point x="0.0" y="1.0" z="-0.5"/> </path> </symmetryobject>

You may have as many symmetry objects in your file as you like. As with Cayley diagrams, they are neither expected nore required, and should only be provided if it makes sense to do so. The name of the symmetry object is given as an attribute of the symmetryobject tag.

The operation tags are a legacy of Group Explorer 1.*, in which you could manipulate symmetry objects while navigating a Cayley diagram. I preserved this information in the event that it might reappear in 2.* some day, but it is not currently used. Each operation tag specifies part of how the group acts on the symmetry object, by mapping group elements to three-dimensional affine transformations which preserve (0,0,0) and handedness--i.e. the rotations about the origin. The element attribute specifies the element in the group whose transformation is to be given. The degrees specify how many degrees are in the rotation, and the point gives a vector (of any length) which is the axis of rotation.

There can be as many more entities in the symmetry object definition as you like. These may be spheres (as above, with a radius, a center, and an HTML RGB-hex color), a path (i.e. a series of joined line segments, with points given), polygons (specified just like paths), and text labels, with the following format.

<label text="what the label says" color="#rrggbb"> <point x="#.#" y="#.#" z="#.#"/></label>

The point in the label is its location in three-space.

One final note about symmetry objects: Any entity in them (sphere, path, polygon, or text) can have the attribute fixed, e.g. <label text="Hello" fixed="Y">, with a yes or no (Y,y,N,n) value. If yes, it means the entity does not move with the rest of the object, but remains rooted in space. One could use this to provide coordinate axes, for example.