Command line interface

Finesse contains a powerful command line interface (CLI), available as a program called kat3 on the same system path where Finesse was installed. The CLI’s primary function is to directly run and display the results from KatScript files, but it also provides various utility and helper functionality as described below.

Quick start

Specifying a script path as the only argument to kat3 will have the CLI parse and run the contents and show the plotted results:

$ kat3 myscript.kat

Hint

The CLI also accepts input from the standard input stream using the Unix convention of specifying a - in place of the path. Power users might find writing e.g. echo "m m1 R=0.99 T=0.01" | kat3 - to be a useful time saver.

The following sections describe how to get help, achieve finer control over simulations, and to perform other tasks with the CLI. A command reference is also provided.

Getting help

To show the various subcommands available in kat3, add the --help flag to the command:

$ kat3 --help
Usage: kat3 [OPTIONS] COMMAND [ARGS]...

  Simulation program for laser interferometers.

Options:
  --banner   Show the Finesse banner and exit.
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  run*     Run a Finesse script.
  config   Configuration information.
  convert  Convert and normalize kat script to canonical form.
  help     Detailed help for KatScript directives.
  info     Print information about a model parsed from a script.
  syntax   Query the KatScript syntax documentation for `query`.

The * next to run indicates that it is the default subcommand assumed when no subcommand is explicitly specified (meaning kat3 myscript.kat is equivalent to kat3 run myscript.kat).

The --help flag can be appended to subcommands too:

$ kat3 info --help
Usage: kat3 info [OPTIONS] INPUT_FILE

  Print information about a model parsed from a script.

Options:
  --summary / --no-summary        Show summary.  [default: summary]
  --graph / --no-graph            Show graph.
  -t, --type [full|components|optical]
                                  Network to plot.
  --layout TEXT                   Graph layout algorithm to use.
  --graphviz                      Generate layout and display using Graphviz.
  --list-graph-layouts            Show available graph layouts and exit.
  --legacy                        Specify that the input file uses Finesse 2
                                  syntax.
  -v, --verbose                   Increase verbosity of log output (can be
                                  specified multiple times).
  -q, --quiet                     Decrease verbosity of log output (can be
                                  specified multiple times).
  --fancy-errors / --no-fancy-errors
                                  Highlight script error locations in red
                                  rather than marking them on the following
                                  line.  [default: fancy-errors]
  --debug                         Enable debug mode (print tracebacks).
  --log-level [warning|info|debug]
                                  Set minimum log severity level to display.
                                  [default: warning]
  --log-exclude TEXT              Ignore log records from a particular logger
                                  (wildcards allowed).
  --help                          Show this message and exit.

Running KatScript files

More control over how simulations are run and how their results are displayed is provided by the kat3 run subcommand. It can control whether to show or hide plots, trace results and other model information, and can enable legacy parsing mode:

$ kat3 run --help
Usage: kat3 run [OPTIONS] INPUT_FILE

  Run a Finesse script.

Options:
  --plot / --no-plot              Display results as figure (if possible).
                                  [default: plot]
  --trace / --no-trace            Displays the results of a beam trace of the
                                  model.  [default: no-trace]
  --legacy                        Specify that the input file uses Finesse 2
                                  syntax.
  -v, --verbose                   Increase verbosity of log output (can be
                                  specified multiple times).
  -q, --quiet                     Decrease verbosity of log output (can be
                                  specified multiple times).
  --fancy-errors / --no-fancy-errors
                                  Highlight script error locations in red
                                  rather than marking them on the following
                                  line.  [default: fancy-errors]
  --debug                         Enable debug mode (print tracebacks).
  --log-level [warning|info|debug]
                                  Set minimum log severity level to display.
                                  [default: warning]
  --log-exclude TEXT              Ignore log records from a particular logger
                                  (wildcards allowed).
  --help                          Show this message and exit.

Looking up KatScript syntax

The kat3 syntax subcommand shows the available KatScript elements, commands and analyses. When executed without arguments, it outputs the full list in a way that is convenient to command line tools like grep. You may optionally specify search terms, which can contain simple wildcards:

  • * matches 0 or more characters

  • ? matches any single character

  • [abc] matches any characters in abc

  • [!abc] matches any characters not in abc

For example, all directives containing “pd” can be found with:

$ kat3 syntax "*pd*"
pd / PowerDetector / power_detector_dc: pd name node pdtype=none

pd1 / PowerDetectorDemod1 / power_detector_demod_1: pd1 name node f phase=none pdtype=none

pd2 / PowerDetectorDemod2 / power_detector_demod_2: pd2 name node f1 phase1 f2 phase2=none pdtype=none

UpdateMaps / update_maps: update_maps(*args, name='update_maps', **kwargs)

Similarly, all “pd<N>” directives can be found with:

$ kat3 syntax "pd?"
pd1 / PowerDetectorDemod1 / power_detector_demod_1: pd1 name node f phase=none pdtype=none

pd2 / PowerDetectorDemod2 / power_detector_demod_2: pd2 name node f1 phase1 f2 phase2=none pdtype=none

Warning

Most shells interpret patterns containing asterisk characters (*) as wildcards matching files in the current directory, and substitute these into the command passed to the program, in this case as extra search queries. Specify the search pattern(s) inside quotes (e.g. "pd*") to avoid potentially unintended matches.

Controlling verbosity

Various flags are available in the CLI to show, filter and hide warnings, errors and debug information produced by Finesse.

Showing or hiding log messages

Various parts of the Finesse code generate messages that can be useful to inform the user of interesting decisions, events, warnings, and errors during execution. This can assist in debugging KatScript or Finesse itself, or to indicate potential pitfalls. Messages are emitted in channels with names that correspond to the area of the code that created them.

Messages from any channel with WARNING, ERROR or CRITICAL severity are shown by default when running a command via the CLI. Log messages with lower severity can be made visible through use of the --verbose (or abbreviated -v) flag on any command. Specifying it once will result in INFO messages becoming visible, and specifying it a further time (i.e. -vv) will make DEBUG messages become visible. In contrast, specifying --quiet (or abbreviated -q) one or more times will make Finesse show only ERROR and CRITICAL messages, respectively.

Note

DEBUG logs contain a huge amount of data and are typically only useful for Finesse developers. It is not recommended to enable debug verbosity unless asked by a developer.

Errors that result in execution halting (such as KatScript syntax errors) are always displayed regardless of the verbosity settings here.

Hint

You may wish to exclude particular log channels from being displayed by the command line interface. For instance, enabling DEBUG verbosity results in a large quantity of messages, some of which you may not be interested in seeing. Channels can be disabled by passing one or more --log-exclude flags with exclude patterns. The same wildcards as those in Looking up KatScript syntax are supported.

For example, to exclude channels containing script, specify --log-exclude *script*.

Showing tracebacks

By default, tracebacks generated by Python when uncaught exceptions occur are suppressed, with only the error message being displayed. This suppression can be switched off by enabling debug mode with the flag --debug.

Fancy error messages

When the current terminal supports it, the locations of errors in KatScript are by default displayed with red text in corresponding error messages. If this behaviour is not desired, it can be switched off with --no-fancy-errors, whereupon the behaviour will instead be to display markers (^ characters) on the line below the part(s) of the script that contains the error(s).

Keeping multiple plots open using job control

You may wish to keep the plot results from a simulation open while performing another, e.g. to be able to compare them. This is possible to do using features provided in command shells on most platforms. Guidance for specific shells is provided below.

See also

Another way to keep old plots “open” is to use an interactive notebook such as JupyterLab.

Bourne-compatible shells (e.g. ‘bash’)

The ampersand (&) operator can be appended to the end of a command to execute it in a background process, which has the effect of running the command but freeing up the shell for subsequent commands rather than blocking it:

$ kat3 run myscript.kat &

A command started in the foreground (that is to say, without an &) can be moved to the background to free up the shell for another command by first suspending its execution using Ctrl + Z then executing the command bg. To return the job to the foreground again, the command fg can be used. When there are multiple commands running in the background, they can be listed with jobs, and the job number N can be brought to the foreground with %N.

Windows command prompt

Jobs can be started in the background by prepending the command with START /B:

C:\> START /B kat3 run myscript.kat

Command reference

Shared options

Many kat3 CLI subcommands share the following common options:

-v, --verbose

Increase verbosity of log output. Specify multiple times to increase verbosity further. See Controlling verbosity for more information.

-q, --quiet

Decrease verbosity of log output. Specify multiple times to decrease verbosity further. See Controlling verbosity for more information.

--fancy-errors, --no-fancy-errors

Highlight script error locations in red rather than marking them on the following line. See Controlling verbosity for more information. On by default.

--debug

Display full exception tracebacks. See Controlling verbosity for more information.

--log-exclude PATTERN

Ignore log records from channels matching PATTERN. See Controlling verbosity for more information.

--legacy

Parse INPUT_FILE as Finesse 2 style KatScript. See Finesse 2 support for more information.

--help

Display help text for the current command.

kat3

Simulation program for laser interferometers.

INPUT_FILE

The path to the input file to run. The destination must exist and be readable by the current user. Use - to denote the standard input stream.

kat3 info

Print information about a model parsed from a script.

INPUT_FILE

The path to the input file to run. The destination must exist and be readable by the current user. Use - to denote the standard input stream.

--summary, --no-summary

Print summary of parsed model. Enabled by default.

--graph, --no-graph

Display graph of parsed model. Disabled by default.

-t, --type

Network type to display when --graph is specified. Choose from “full”, “components”, or “optical”.

--layout LAYOUT

Graph layout to use when --graph is specified. Use --list-graph-layouts to print a list of available layouts.

--graphviz

Use Graphviz (via pygraphviz) to display the resulting graph, rather than networkx. Graphviz and pygraphviz must be installed for this option to work.

--list-graph-layouts

Print available graph layouts. This will contain at least those of networkx. If pygraphviz is installed, additional Graphviz-based layouts will be available.

kat3 syntax

Query the kat script syntax documentation.

QUERY

Search term. May be specified zero or more times. Basic wildcard syntax is supported:

  • * matches 0 or more characters

  • ? matches any single character

  • [abc] matches any characters in abc

  • [!abc] matches any characters not in abc

--elements, --commands, --analyses

Limit the matched results to only elements, commands and/or analyses.

kat3 convert

Convert and normalize kat script to canonical form.

This can be used to convert Finesse 2 or Finesse 3 scripts to canonical Finesse 3 form. The resulting script is arranged in standard order and with standard spacing.

If OUTPUT_FILE is not specified, it defaults to standard output.

To parse Finesse 2 files, specify --legacy.

Warning

This is an experimental command. It may not generate accurate nor valid KatScript!

INPUT_FILE

The path to the input file to convert. The destination must exist and be readable by the current user. Use - to denote the standard input stream.

OUTPUT_FILE

The path to the output file to write. The destination must be writable by the current user. Defaults to -, indicating the standard output stream.