Getting help

For general or technical questions on using Finesse we have a user chat channel on Matrix.

This is open to the general public and is the easiest way to get help.

There is also a mailing list which can also be used for those that prefer email over Matrix, finesse-users AT nikhef.nl.

For users within the gravitational wave community we also have an active chat channel https://chat.ligo.org/ligo/channels/finesse. This will require you to log in with your Albert.Einstein credentials.

Reporting issues

You can automatically generate a helpful bug report in markdown format by calling finesse.utilities.bug_report.bug_report(). This will include some information about your system and python installation, and optionally includes the code from the file you are calling it in and the last exception that was raised.

If you want to use it in a script, you should catch the exception to report it:

import finesse

try:
    1 / 0
except Exception:
    report = finesse.bug_report(file="bug_report.md")
    print(report)

Bug report written to /builds/ifosim/finesse/finesse3/docs/bug_report.md

# Finesse3 bug report

## Environment

- **Finesse version:** `3.0b3`
- **Python version:** `3.13.12 (main, Feb 24 2026, 21:47:07) [GCC 14.2.0]`
- **Platform:** `Linux x86_64`

## Entry point

`/usr/local/bin/python3.13`

### Arguments

`/usr/local/lib/python3.13/site-packages/ipykernel_launcher.py` `-f` `/tmp/tmp_773_uup.json` `--HistoryManager.hist_file=:memory:`

## Stack trace

```text
Traceback (most recent call last):
  File "/tmp/ipykernel_1006/3840209720.py", line 4, in <module>
    1 / 0
    ~~^~~
ZeroDivisionError: division by zero

```

## Package versions

```text
IPython == 9.10.0
asttokens == 3.0.1
babel == 2.18.0
charset_normalizer == 3.4.4
click == 8.3.1
comm == 0.2.3
cycler == 0.12.1
debugpy == 1.8.20
decorator == 5.2.1
defusedxml == 0.7.1
deprecated == 1.3.1
dill == 0.4.1
docutils == 0.21.2
executing == 2.2.1
finesse == 3.0b3
h5py == 3.15.1
ipykernel == 7.2.0
ipywidgets == 8.1.8
jedi == 0.19.2
jinja2 == 3.1.6
jupyter_client == 8.8.0
jupyter_core == 5.9.1
kiwisolver == 1.4.9
markupsafe == 3.0.3
matplotlib == 3.10.8
more_itertools == 10.8.0
msgpack == 1.1.2
networkx == 3.6.1
numpy == 2.4.2
numpydoc == 1.10.0
packaging == 26.0
parso == 0.8.6
platformdirs == 4.9.2
prompt_toolkit == 3.0.52
psutil == 7.2.2
pure_eval == 0.2.3
pygments == 2.19.2
pyparsing == 3.3.2
quantiphy == 2.21
scipy == 1.17.1
six == 1.17.0
sphinx == 8.2.3
sphinx_jinja2_compat == 0.4.1
sphinx_prompt == 1.10.2
sphinx_prompt == 1.10.2
stack_data == 0.6.3
tornado == 6.5.4
tqdm == 4.67.3
traitlets == 5.14.3
wcwidth == 0.6.0
wrapt == 2.1.1
PIL
__future__
__main__
__main__
_abc
_ast
_asyncio
_bisect
_blake2
_bz2
_codecs
_collections
_colorize
_compat_pickle
_compression
_contextvars
_csv
_ctypes
_curses
_cython_3_0_11
_cython_3_1_3limited_fastcallnofinalize
_cython_3_1_4
_cython_3_2_4
_datetime
_decimal
_distutils_hack
_elementtree
_functools
_hashlib
_heapq
_imp
_io
_json
_locale
_lsprof
_lzma
_multibytecodec
_opcode
_opcode_metadata
_operator
_pickle
_posixsubprocess
_pydev_bundle
_pydev_runfiles
_pydevd_bundle
_pydevd_frame_eval
_pydevd_sys_monitoring
_pyio
_pyrepl
_queue
_random
_signal
_sitebuiltins
_socket
_sqlite3
_sre
_ssl
_stat
_string
_strptime
_struct
_sysconfigdata__linux_x86_64-linux-gnu
_thread
_tokenize
_typing
_uuid
_warnings
_weakref
_weakrefset
_zoneinfo
abc
argparse
array
ast
asyncio
atexit
base64
bdb
binascii
bisect
builtins
bz2
cProfile
calendar
cmath
cmd
code
codecs
codeop
collections
colorsys
concurrent
configparser
contextlib
contextvars
copy
copyreg
csv
ctypes
curses
cython_runtime
dataclasses
datetime
dateutil
decimal
difflib
dis
email
encodings
enum
errno
faulthandler
fcntl
filecmp
fileinput
finesse_numpydoc
fnmatch
fractions
functools
gc
genericpath
getopt
getpass
gettext
glob
grp
gzip
hashlib
heapq
hmac
html
http
importlib
inspect
io
ipaddress
itertools
json
keyword
linecache
locale
logging
lzma
marshal
math
mimetypes
mpl_toolkits
multiprocessing
ntpath
numbers
opcode
operator
optparse
os
pathlib
pdb
pickle
pkgutil
platform
plistlib
posix
posixpath
posixpath
pprint
profile
pstats
pwd
pydev_ipython
pydevconsole
pydevd
pydevd_file_utils
pydevd_plugins
pydevd_tracing
pydoc
pydoc_data
pyexpat
queue
quopri
random
re
readline
reprlib
resource
runpy
secrets
select
selectors
shlex
shutil
signal
site
socket
socketserver
spellchecker
sphinxcontrib
sqlite3
ssl
stat
string
stringprep
struct
subprocess
sys
sysconfig
tempfile
termios
textwrap
threading
time
timeit
token
tokenize
traceback
types
typing
unicodedata
unittest
urllib
uuid
warnings
weakref
webbrowser
xml
xmlrpc
zipfile
zipimport
zlib
zmq
zoneinfo

```

In an interactive notebook environment, you can call the function from a separate cell to grab the last exception and that will also work. It will return the report as a string and safe it to bug_report.md.

Warning

You can optionally include the source code of the file causing the exception in your report by passing include_source=True to finesse.utilities.bug_report.bug_report() , but you might unintentionally leak proprietary/confidential information by posting the report in a public space.

You can copy the contents directly into the Matrix channel or create a gitlab issue

Finesse and KatScript objects

Refer to the rest of this documentation for information on the use of KatScript and Finesse objects.

Interactive help

The finesse.help() function accepts either a string or object as input and will show corresponding help. If a string is provided, it is assumed to be a KatScript path like m, beamsplitter, or bs.T. Command names such as xaxis are also supported.

This operates similarly to the Python built-in function help(): either a pager is opened (if using a console; use PgUp and PgDn to navigate, and q to escape) or the help text is printed (if using a notebook).