PTS includes a number of Python scripts that can be invoked directly from the command line. This topic introduces the use of these command scripts. The discussion is organized in the following sections:

Also see the following topics with information on specific PTS command script categories:

Invoking command scripts

Note: To enable the PTS command script machinery in a terminal session, the PYTHONPATH environment variable must have been properly defined and an appropriate alias for "pts" must have been declared. This is usually accomplished in the login shell script, and should have been setup during the installation of PTS. For more information, refer to Configuring PTS paths and aliases in the installation guide.

The syntax for invoking a PTS command script from the command line is:

pts packagename/scriptname argument1 argument2 ...

The first argument on the command line (after "pts") must specify the package and script names separated by a forward slash. The remaining command line arguments are passed to the script.

Several shortcuts are allowed for the package and script names, as long as these shortcuts do not result in any ambiguities. The package name can be omitted, and if the script name contains underscores, each of the segments between the underscores can be used instead of the full script name. Also, any name can be shortened to an initial subset of the name.

For example, the admin/try_do command script accepts a single string as a positional argument. Assuming that none of the other command scripts match the same shortcut, this script can be accessed by any of the following commands:

pts admin/try_do me
pts ad/tr me
pts tr me
pts do me

All command scripts support the --help option. For example:

$ pts try --help
usage: pts [-h] [--aString <str>] [--aFloat <float>] [--anInteger <int>]
           admin/try_do aFixedString

admin/try_do: try the PTS command mechanism

positional arguments:
  admin/try_do       packagename/scriptname
  aFixedString       first and only positional argument

optional arguments:
  -h, --help         show this help message and exit
  --aString <str>    optional string argument (default: PTS is great)
  --aFloat <float>   optional float argument (default: 3.14)
  --anInteger <int>  optional integer argument (default: 7)

This means that the admin/try_do command script accepts three optional, non-positional arguments in addition to the single positional string argument. For demonstration purposes, the optional arguments each have a different data type: string, floating point number, and integer number. To pass a string that may contain whitespace or other special characters, use quotes. For example:

$ pts try "you and me" --aFloat 8.3 --anInteger 17
Starting admin/try_do...
Command line arguments are:
  Fixed string:    you and me
  Optional string: PTS is great
  Float number:    8.3
  Integer number:  17
Finished admin/try_do...

Overview of the available command scripts

The following table lists the PTS packages with a brief description of its capabilities and a link to the reference documentation of its command scripts.

Package	Commands	Description
admin	pts.admin.do	Administrative functions
band	pts.band.do	Representing broadband filters
do	-	Accessing PTS from the command line
simulation	pts.simulation.do	Interfacing with SKIRT and its input/output files
skiupgrade	pts.skiupgrade.do	Upgrading SKIRT parameter files
storedtable	pts.storedtable.do	Handling the SKIRT stored table file format
test	pts.test.do	Performing and reporting on SKIRT functional tests
utils	-	Utilities for use by other PTS components
visual	pts.visual.do	Visualizing SKIRT results

To see a list of all available PTS command scripts with a brief description of their function, use the admin/list_commands command script:

$ pts list_commands
  Starting admin/list_commands...
  Package admin:
    admin/list_commands: list all PTS command scripts
    admin/list_dependencies: list external package dependencies for PTS
    ...
  Package visual:
    visual/make_images: create RGB images for surface brightness maps generated by SKIRT instruments
    visual/plot_bands: plot built-in broadbands in a given wavelength range
    visual/plot_density: plot planar density cuts or projections from one or more SKIRT simulations
    ...
  Finished admin/list_commands.