Ctrl+K

Running improv

Running improv#

Basic invocation#

While improv can be invoked via API, the simplest method is to run it from the improv command line interface:

!improv --help

usage: improv [-h] {run,client,server,list,cleanup} ...

Command line tool for improv.

options:
  -h, --help            show this help message and exit

subcommands:
  {run,client,server,list,cleanup}
                        for launching individual components

The most basic command is improv run:

!improv run --help

usage: improv run [-h] [-c CONTROL_PORT] [-o OUTPUT_PORT] [-l LOGGING_PORT]
                  [-f LOGFILE] [-a ACTOR_PATH]
                  configfile

Start the improv client and server together

positional arguments:
  configfile            YAML file specifying improv pipeline

options:
  -h, --help            show this help message and exit
  -c CONTROL_PORT, --control-port CONTROL_PORT
                        local port on which control are sent to/from server
  -o OUTPUT_PORT, --output-port OUTPUT_PORT
                        local port on which server output messages are
                        broadcast
  -l LOGGING_PORT, --logging-port LOGGING_PORT
                        local port on which logging messages are broadcast
  -f LOGFILE, --logfile LOGFILE
                        name of log file
  -a ACTOR_PATH, --actor-path ACTOR_PATH
                        search path to add to sys.path when looking for
                        actors; defaults to the directory containing
                        configfile

For instance, if you run the minimal demo

improv run demos/minimal/minimal.yaml

improv will use the YAML file to setup up and run both the improv server and the improv client, which is a text user interface (TUI):



In the text window, we can issue commands to the improv server:

  • setup: to initialize all actors and create their connections

  • run: to start the experiment

  • stop: to send the stop signal to all actors

  • quit: to initiate cleanup and exit the TUI.

More details can be found at Signals and communicating between actors.

Command line options#

For more advanced usage, improv run lets you specify the ports to use for communicating with the server and client (the default is to use random available ports), as well as specifying the name of the log file. The default is to append to global.log, so be sure to either (a) delete this file periodically (not recommended) or (b) use a unique log file name for each experiment.

Tip

A particularly important command line option is --actor-path or -a, which gives a list of directories in which to search for the Python modules containing actors. The default actor path is the directory containing the configuration file.

Other subcommands#

In addition, for running improv across multiple machines, there is the improv server command

!improv server --help

usage: improv server [-h] [-c CONTROL_PORT] [-o OUTPUT_PORT] [-l LOGGING_PORT]
                     [-f LOGFILE] [-a ACTOR_PATH]
                     configfile

Start the improv server

positional arguments:
  configfile            YAML file specifying improv pipeline

options:
  -h, --help            show this help message and exit
  -c CONTROL_PORT, --control-port CONTROL_PORT
                        local port on which control signals are received
  -o OUTPUT_PORT, --output-port OUTPUT_PORT
                        local port on which output messages are broadcast
  -l LOGGING_PORT, --logging-port LOGGING_PORT
                        local port on which logging messages are broadcast
  -f LOGFILE, --logfile LOGFILE
                        name of log file
  -a ACTOR_PATH, --actor-path ACTOR_PATH
                        search path to add to sys.path when looking for
                        actors; defaults to the directory containing
                        configfile

to start the server and improv client to start a client locally:

!improv client --help

usage: improv client [-h] [-c CONTROL_PORT] [-s SERVER_PORT] [-l LOGGING_PORT]

Start the improv client

options:
  -h, --help            show this help message and exit
  -c CONTROL_PORT, --control-port CONTROL_PORT
                        address on which control signals are sent to the
                        server
  -s SERVER_PORT, --server-port SERVER_PORT
                        address on which messages from the server are received
  -l LOGGING_PORT, --logging-port LOGGING_PORT
                        address on which logging messages are broadcast

Note

When running clients and servers on different machines, you will need to know and specify the relevant ports, so it may be good to select these manually.

Cleaning up#

Finally, it occasionally happens that processes do not shut down cleanly. This can leave orphaned processes running on the system, which quickly eats memory. To see these processes, you can run improv list, which will show all processes currently associated with improv. Running improv cleanup will prompt before killing all these processes.

Contents