# Working with Packets

## The Packet Tree

A single Regina data file can store a rich variety of objects, from knots, 3-manifold triangulations and normal surfaces through to &python; scripts, &pdf; documents and text notes. All of these objects are called packets, and are arranged in a tree-like structure as you can see below.

To view or edit a packet, just click on the packet in the tree (on some platforms, such as &macosx;, you need to double-click instead). The packet will open up in a new window, as shown below.

## Different Packet Types

There are many different types of packet that you can create in ®ina;. Here we give a brief overview of each.

### Container Packets

A container packet helps keep your packet tree organised: it can contain other “child” packets, but otherwise it does nothing.

Containers are marked by the following icon:

To see how containers can be used to organise a tree, take a look at one of the census files: try File Open Example Closed Non-Orientable Census . Part of the packet tree for this census is shown below (the container labelled 6 tetrahedra has been opened for viewing).

Note that any packet (not just a container) can contain other child packets.

### 2-Manifold Triangulations

A 2-manifold triangulation packet describes a triangulated 2-manifold, formed by gluing edges of triangles together in pairs.

2-manifold triangulations are marked by the following icon:

### 3-Manifold Triangulations

A 3-manifold triangulation packet describes a triangulated 3-manifold, formed by gluing faces of tetrahedra together in pairs. 3-manifold triangulations are central to ®ina;, and you can learn more about using them by reading the triangulations chapter in this handbook.

3-manifold triangulations are marked by the following icon:

### &snappea; Triangulations

A &snappea; triangulation packet stores a 3-manifold using &snappea;'s internal data structures (in contrast, the usual 3-manifold triangulation packet uses ®ina;'s own structures, which are independent of &snappea;). You can learn more about using &snappea; triangulations in the corresponding chapter later in this handbook.

The advantages of using a &snappea; triangulation is that it stores additional information that ®ina; does not (such as fillings and peripheral curves), and it offers more direct access to the &snappea; kernel. The main disadvantage is that you do not have the fine-grained control over the triangulation that ®ina; offers you (in particular, you cannot manipulate the triangulation as freely). Of course ®ina; offers you facilities to convert one into the other.

&snappea; triangulations are marked by the following icon:

### 4-Manifold Triangulations

A 4-manifold triangulation packet describes a triangulated 4-manifold, formed by gluing faces of pentachora (i.e., 4-simplices) together in pairs. You can learn more about 4-manifold triangulations by reading the triangulations chapter in this handbook.

4-manifold triangulations are marked by the following icon:

### Higher-Dimensional Triangulations

®ina; currently offers very basic support for triangulations of dimensions 5–8 (and, with your own custom build, 9–15). At present you cannot work with these higher-dimensional triangulations in the &gui;—instead you will need to use either &python; scripting or &cpp; programming.

Triangulations of these higher dimensions are marked by an icon similar to the following, with the dimension marked inside the simplex-shaped outline:

The packet viewer offers very little information, but it does include a button to open a &python; console, where you can analyse and/or modify the triangulation further.

### Knots and Links

A link packet describes a knot or link diagram, formed from a collection of crossings and strands that connect them. You can learn more about working with links by reading the knots and links chapter in this handbook.

Knots and links are marked by the following icon:

### Normal Surface Lists

A normal surface list represents a set of normal surfaces within a 3-manifold triangulation. Typically this will be the set of all vertex or fundamental surfaces in some normal (or almost normal) coordinate system. Like triangulations, normal surfaces are central to ®ina;, and you can learn more about using them in the chapter on normal surfaces and hypersurfaces.

Normal surface lists are marked by the following icon:

Normal surface lists can be created using different sets of matching equations, and can then be viewed in a variety of coordinate systems. As of ®ina; 7.0, a normal surface list can appear anywhere in the packet tree (it no longer needs to be linked to its source 3-manifold triangulation).

### Normal Hypersurface Lists

A normal hypersurface list represents a set of normal hypersurfaces within a 4-manifold triangulation. As with normal surface lists, this will typically be the set of all vertex or fundamental hypersurfaces in some normal coordinate system. You can learn more about them in the chapter on normal surfaces and hypersurfaces.

Normal hypersurface lists are marked by the following icon:

Normal hypersurface lists can be also created using different sets of matching equations, and can be viewed in different coordinate systems. Like normal surfaces, a normal hypersurface list can appear anywhere in the packet tree (it no longer needs to be linked to its source 4-manifold triangulation).

### Angle Structure Lists

An angle structure list represents a set of angle structures on a 3-manifold triangulation. Typically this will be the set of all vertex angle structures under the standard equations. You can learn more about working with angle structure lists in the chapter on angle structures in this handbook.

Angle structure lists are marked by the following icon:

Like normal surfaces, an angle structure list can appear anywhere in the packet tree (it no longer needs to be linked to its source 3-manifold triangulation).

### Surface Filters

A surface filter can be applied to a long list of normal surfaces to extract only some smaller set of surfaces that you might be interested in. You can learn more about surface filters in the chapter on normal surfaces. ®ina; offers two types of surface filter:

#### Property Filters

A property filter selects only those normal surfaces with a given orientability, compactness, boundary, and/or Euler characteristic.

Property filters are marked by the following icon:

#### Combination Filters

A combination filter uses boolean `AND` or `OR` to combine several other surface filters. This allows you to combine property filters together in complex boolean expressions.

Combination filters are marked by the following icon:

A combination filter will combine its immediate children in the packet tree. For example, the combination filter illustrated below will select any surface that passes either the Tori and Annuli filter or the Discs filter.

### Text Packets

A text packet contains an arbitrary amount of plain text, with no formatting. It can be used to add descriptions, observations or other miscellaneous comments into your data file.

Text packets are marked by the following icon:

### Script Packets

A script packet contains a &python; script that offers direct access to ®ina;'s calculation engine. You can edit the script from within ®ina;, and your script can set variables that represent other packets in your data file. See the chapter on &python; for more information on scripting within ®ina;.

Script packets are marked by the following icon:

### Attachments

An attachment packet allows you embed any external file into your ®ina; data file. The external file will be copied and saved as part of your ®ina; data file (which means that if you send a ®ina; data file to someone, all attachments will be automatically included).

&pdf; packets are marked by the following icon:

One potential use of attachments is to help you document your work. As seen in the example below, an attachment could be a &pdf; document containing rich content such as diagrams and formulae.

When you open an attachment for viewing, you will be told the filename and file size, and given the opportunity to either view it (using your computer's default viewer for that type of file), or to save it.

To insert a new attachment into your ®ina; data file, select Packet Tree New Attachment . Once your attachment has been inserted, you can edit, move or even delete the original file from your computer, since your ®ina; data file will keep its own internal copy.

In ®ina; 6.0.1 and earlier, this type of packet was called a &pdf; packet, and was used exclusively for &pdf; documents. As of ®ina; 7.0, you can now attach any type of file.

## General Operations on Packets

The Packet Tree menu contains operations that can be applied to any packet in ®ina;. Most of these operations are also offered as toolbar buttons. Here we describe each of these operations in turn.

### Creating New Packets

New packets of any type can be created through the corresponding New ... item in the Packet Tree menu, or by pressing the toolbar button with the corresponding packet icon.

For example, to create a new 3-manifold triangulation, either select Packet Tree New 3-D Triangulation in the menu, or press the toolbar button with the following icon:

When you create a new packet, you will be asked where in the tree your new packet should appear. Choose a suitable parent in the box marked Create beneath:, and your new packet will be added as a child of whatever you choose here.

You might also be asked for some additional information, according to which type of packet you are creating. In the example above, you must select the type of triangulation to create; moreover, since the user has selected to use an isomorphism signature, you must type in the isomorphism signature as well.

The new packet will be given a label automatically, though you can of course rename it if you like.

### Cloning Packets

To make an identical copy of an existing packet, you can use either the Packet Tree Clone Packet or the Packet Tree Clone Subtree menu item. ®ina; will clone whatever packet is currently selected, and the clone will be added adjacent to it in the tree.

If you choose Clone Packet, only the selected packet will be copied (not any of its children). If you choose Clone Subtree, ®ina; will clone not only the selected packet but also the entire subtree beneath it (&ie;, its children, their children and so on).

If you have selected some packet in the tree but you have different packets open for viewing or editing, it is the selected packet in the tree that will be cloned, not the packets that you are currently viewing.

### Renaming Packets

By selecting Packet Tree Rename from the menu (or the corresponding toolbar button), you can give the selected packet a new label.

If you have selected some packet in the tree but you have different packets open for viewing or editing, it is the selected packet in the tree that will be renamed, not the packets that you are currently viewing.

### Deleting Packets and Subtrees

If you select Packet Tree Delete from the menu (or press the corresponding toolbar button), whatever packet you have selected in the tree will be deleted. Note that all children of the selected packet will also be deleted, and their children and so on.

If you have selected some packet in the tree but you have different packets open for viewing or editing, it is the selected packet in the tree that will be deleted, not the packets that you are currently viewing. Be careful, since deleting a packet cannot be undone!

### Moving Around the Tree

The Packet Tree Move submenu allows you to reorganise your packet tree by moving packets around. Whenever a packet moves, all of its children (and their children and so on) will move along with it.

Selecting Higher Level or Lower Level will move the selected packet to a different parent (either shallower or deeper in the tree respectively). The remaining options will keep the same parent, but will move the selected packet up or down with respect to its “siblings”. Up or Down will move the packet by one step, and Top or Bottom will make it the first or last child respectively of its parent. Jump Up or Jump Down will move the packet several steps at a time; the precise number of steps can be configured in ®ina;'s general settings.

All of the actions in the Packet Tree Move menu have keyboard shortcuts, allowing you to reorganise the packet tree quickly using just the keyboard.