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
if __name__ == "__main__":
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.0a29`
- **Python version:** `3.12.7 (main, Nov 12 2024, 06:04:35) [GCC 12.2.0]`
- **Platform:** `Linux x86_64`
## Entry point
`/usr/local/bin/python3.12`
### Arguments
`/usr/local/lib/python3.12/site-packages/ipykernel_launcher.py` `-f` `/tmp/tmp5101hzz0.json` `--HistoryManager.hist_file=:memory:`
## Stack trace
```text
Traceback (most recent call last):
File "/tmp/ipykernel_1679/568623899.py", line 5, in <module>
1 / 0
~~^~~
ZeroDivisionError: division by zero
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "/usr/local/lib/python3.12/site-packages/finesse/utilities/bug_report.py", line 180, in get_formatted_traceback
traceback.print_last(file=io)
File "/usr/local/lib/python3.12/traceback.py", line 189, in print_last
raise ValueError("no last exception")
ValueError: no last exception
```
## Package versions
```text
re == 2.2.1
ipaddress == 1.0
json == 2.0.9
platform == 1.0.8
zmq == 26.2.0
logging == 0.5.1.2
traitlets == 5.14.3
jupyter_core == 5.7.2
zlib == 1.0
_curses == b'2.2'
socketserver == 0.4
argparse == 1.1
dateutil == 2.9.0.post0
six == 1.16.0
decimal == 1.70
decimal == 1.70
platformdirs == 4.3.6
_csv == 1.0
csv == 1.0
jupyter_client == 8.6.3
ipykernel == 6.29.5
executing == 2.1.0
pure_eval == 0.2.3
stack_data == 0.6.3
pygments == 2.18.0
decorator == 5.1.1
wcwidth == 0.2.13
prompt_toolkit == 3.0.48
parso == 0.8.4
jedi == 0.19.2
IPython == 8.29.0
comm == 0.2.2
psutil == 6.1.0
packaging == 24.2
_ctypes == 1.1.0
ctypes == 1.1.0
debugpy == 1.8.8
pydevd == 3.2.2
numpy == 2.1.3
h5py == 3.12.1
PIL == 11.0.0
defusedxml == 0.7.1
pyparsing == 3.2.0
cycler == 0.12.1
kiwisolver == 1.4.7
matplotlib == 3.9.2
networkx == 3.4.2
scipy == 1.14.1
mpmath == 1.3.0
sympy == 1.13.3
charset_normalizer == 3.4.0
spellchecker == 0.8.1
quantiphy == 2.20
click == 8.1.7
wrapt == 1.16.0
deprecated == 1.2.14
numpydoc == 1.6.0
more_itertools == 10.5.0
tqdm == 4.67.0
ipywidgets == 8.1.5
finesse == 3.0a29
```
In an interactive notebook environment, you can call the function from a separate cell to grab the last exception:
1/0
---------------------------------------------------------------------------
ZeroDivisionError Traceback (most recent call last)
Cell In[2], line 1
----> 1 1/0
ZeroDivisionError: division by zero
import finesse
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.0a29`
- **Python version:** `3.12.7 (main, Nov 12 2024, 06:04:35) [GCC 12.2.0]`
- **Platform:** `Linux x86_64`
## Entry point
`/usr/local/bin/python3.12`
### Arguments
`/usr/local/lib/python3.12/site-packages/ipykernel_launcher.py` `-f` `/tmp/tmp5101hzz0.json` `--HistoryManager.hist_file=:memory:`
## Stack trace
```text
Traceback (most recent call last):
File "/usr/local/lib/python3.12/site-packages/IPython/core/interactiveshell.py", line 3577, in run_code
exec(code_obj, self.user_global_ns, self.user_ns)
File "/tmp/ipykernel_1679/2354412189.py", line 1, in <module>
1/0
~^~
ZeroDivisionError: division by zero
```
## Package versions
```text
re == 2.2.1
ipaddress == 1.0
json == 2.0.9
platform == 1.0.8
zmq == 26.2.0
logging == 0.5.1.2
traitlets == 5.14.3
jupyter_core == 5.7.2
zlib == 1.0
_curses == b'2.2'
socketserver == 0.4
argparse == 1.1
dateutil == 2.9.0.post0
six == 1.16.0
decimal == 1.70
decimal == 1.70
platformdirs == 4.3.6
_csv == 1.0
csv == 1.0
jupyter_client == 8.6.3
ipykernel == 6.29.5
executing == 2.1.0
pure_eval == 0.2.3
stack_data == 0.6.3
pygments == 2.18.0
decorator == 5.1.1
wcwidth == 0.2.13
prompt_toolkit == 3.0.48
parso == 0.8.4
jedi == 0.19.2
IPython == 8.29.0
comm == 0.2.2
psutil == 6.1.0
packaging == 24.2
_ctypes == 1.1.0
ctypes == 1.1.0
debugpy == 1.8.8
pydevd == 3.2.2
numpy == 2.1.3
h5py == 3.12.1
PIL == 11.0.0
defusedxml == 0.7.1
pyparsing == 3.2.0
cycler == 0.12.1
kiwisolver == 1.4.7
matplotlib == 3.9.2
networkx == 3.4.2
scipy == 1.14.1
mpmath == 1.3.0
sympy == 1.13.3
charset_normalizer == 3.4.0
spellchecker == 0.8.1
quantiphy == 2.20
click == 8.1.7
wrapt == 1.16.0
deprecated == 1.2.14
numpydoc == 1.6.0
more_itertools == 10.5.0
tqdm == 4.67.0
ipywidgets == 8.1.5
finesse == 3.0a29
```
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).