.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "KATIE" "1" "25 August 2025" "" "The Regina Handbook"

.SH NAME
katie \- Triangulate a 3-manifold or 4-manifold from a decorated link
.SH SYNOPSIS

\fBkatie\fR \fB\fIpd_code\fB\fR \fB\fIframing_vector\fB\fR [ \fB-3, --dim3\fR | \fB-4, --dim4\fR ] [ \fB-g, --graph\fR ] [ \fB-V, --verbose\fR ]


\fBkatie\fR { \fB-v, --version\fR | \fB-?, --help\fR }

.SH "DESCRIPTION"
.PP
This utility builds a triangulation or coloured graph of a
3-manifold or 4-manifold from a decorated link.
.PP
For 3-manifolds, the manifold constructed is the one obtained by
performing integer Dehn surgery on the given link.
.PP
For 4-manifolds, the manifold constructed is the one obtained by attaching
4-dimensional 1- and 2-handles to the 4-ball along the dotted and 
framed link components, respectively.
.PP
\fBKatie\fR expects two arguments at runtime: the underlying (undecorated) link,
and a list of space-separated decorations (framing coefficients and/or
1-handle "markers").
.TP 0.2i
\(bu
The link should be given in the format of a planar diagram (PD) code,
specifically, in the same format as used by \fBSnapPy\fR\&.
The simplest way to achieve this is to draw the link in \fBSnapPy\fR\&'s
\fBPLink\fR editor, and copy the PD code generated by \fBSnapPy\fR via the
InfoPD\~Code
menu option in the editor.
.TP 0.2i
\(bu
Within the framing sequence, use \&'x' or
\&'.' to denote 1-handles.
.sp
.RS
.B "Warning:"
The PD code and the framing sequence must appear as the first two
arguments.  If you are running \fBKatie\fR from a shell, you will
need to wrap both of these arguments in quotation marks.
.RE
.PP
For more information, see the full \fBKatie\fR manual, available from
 <URL:https://raburke.github.io/>\&.
.SH "OPTIONS"
.TP
\fB-3, --dim3\fR
Build the 3-manifold obtained from integer Dehn surgery on the
input link.

If you do not pass either \fB--dim3\fR or
\fB--dim4\fR, the default is to build a 4-manifold.
.TP
\fB-4, --dim4\fR
Build the 4-manifold obtained by attaching 1- and 2-handles along the
components of the decorated link to the 4-ball.

This option is the default if you do not pass either
\fB--dim3\fR or \fB--dim4\fR\&.
.TP
\fB-g, --graph\fR
Output an edge list of the edge-coloured graph associated to the
manifold. Each node of the graph corresponds to a tetrahedron in the
case of 3-manifolds or to a pentachoron in the case of 4-manifolds.
Two nodes are connected by a \fIc\fR-coloured
edge if the two corresponding top-dimensional simplices of the
triangulation have the facets opposite to the vertex labelled
\fIc\fR identified.
.TP
\fB-V, --verbose\fR
Display information during the construction.
.TP
\fB-v, --version\fR
Show which version of Regina is being used, and exit
immediately.
.TP
\fB-?, --help\fR
Display brief usage information, and exit immediately.
.SH "EXAMPLES"
.PP
The following builds the Poincare homology 3-sphere obtained by
+1 surgery along the right handed trefoil knot.

.nf
    example$ \fBkatie "[(6,4,1,3),(4,2,5,1),(2,6,3,5)]" "1" -3\fR
    Writhes:
    Component 0: 2-handle, writhe 1
    
    Here is the isomorphism signature:
    GLvvQvPvALvzMAQAvAQQQPccgfekjp...
    example$
.fi
.PP
The following builds the complex projective plane by attaching a single
2-handle to the 4-ball along a +1 framed unknot.

.nf
    example$ \fBkatie "[(1,1,2,2)]" "1"\fR
    Writhes:
    Component 0: 2-handle, writhe 1
    
    Here is the isomorphism signature:
    mLvAwAQAPQQcfffhijgjgjkkklklll...
    example$
.fi
.PP
The following builds a 4-manifold containing both a 1- and a 2-handle.

.nf
    example$ \fBkatie "[(4,8,1,9),(9,3,10,4),(1,5,2,6),(6,2,7,3),(7,5,8,10)]" "x 0"\fR
    Writhes:
    Component 0: 1-handle (0)
    Component 1: 2-handle, writhe 0
    
    Here is the isomorphism signature:
    SLvAvAAwvvALMQQPvPvPMQwQAQMAvQ...
    example$
.fi
.SH "MACOS USERS"
.PP
If you downloaded a drag-and-drop app bundle, this utility is
shipped inside it.  If you dragged Regina to the main
Applications folder, you can run it as
/Applications/Regina.app/Contents/MacOS/katie\&.
.SH "WINDOWS USERS"
.PP
The command-line utilities are installed beneath the
\fIProgram\~Files\fR directory; on some
machines this directory is called
\fIProgram\~Files\~(x86)\fR\&.
You can start this utility by running
c:\\Program\~Files\\Regina\\Regina\~7.4.1\\bin\\katie.exe\&.
.SH "AUTHOR"
.PP
This utility was written by Rhuaidi Burke
<rhuaidi.burke@uq.edu.au>\&.
Many people have been involved in the development
of Regina; see the users' handbook for a full list of credits.