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.

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.