The PTS Developer Guide

This page offers some guidance for users and developers who wish to adjust or extend PTS capabilities. It is organized in the following topics:

# Packages, modules and directories

The PTS source code is contained in an online repository and can be obtained as described in The PTS Installation Guide. guide. Your local copy of this repository is usually placed inside a directory called PTS in your home directory. The resulting directory structure may look as follows:

~/PTS
pts
do
band
data
do
do
docs
simulation
...
visual
do
run


The optional run directory may contain input/output files involved in actually running PTS. This information obviously does not belong in the source code repository, which is why the run directory is not inside the pts directory. The contents of the pts directory is an identical clone of the online PTS repository. Immediately inside the pts directory resides a shell script for building the documentation (see Building the documentation) and a number of subdirectories holding the source and documentation files.

A PTS package is represented as a top-level subdirectory of the PTS repository. Each Python source file within a package is called a module. PTS has no nested packages. The following table lists some important packages in PTS with an indication of their functionality.

Package Description
admin Administrative functions, such as listing PTS package dependencies and creating archives for backup purposes
band Representing broadband filters, including transmission curve data for a set of standard bands
simulation Interfacing with the SKIRT executable, the configuration file, and SKIRT output files (with units)
storedtable Converting third-party data to SKIRT stored table format and otherwise accessing files in this format
test Performing and reporting on SKIRT functional tests
utils Basic utilities for use by other sub-packages
visual Visualizing SKIRT results including image frames, SEDs, density cuts, temperature cuts, polarization maps, and more.

In addition to the package subdirectories, the following subdirectories may occur in the repository directory hierarchy as needed:

Subdirectory Where Presence Description
docs Top-level Mandatory Configuration files for building HTML pages from the comment blocks embedded in the PTS source code
do Top-level Mandatory Implementation of command line facilities, i.e. locating and executing scripts in do subdirectories
do Inside package Optional Command scripts that can be executed directly from the PTS command line
data Inside package Optional Data resources required by the module containing this directory

# Coding style

## Basic conventions

PTS is written in Python 3.7 and, in general, uses the coding style, language capabilities and standard library functions corresponding to that language version.

As an important exception to this rule, the comment blocks preceding classes and functions in the code use the ## style as opposed to the more pythonic doc-string style. The main reason is that Doxygen does not recognize the special commands for LaTeX contents, extra formatting, and hyperlinks in doc strings.

The following table summarize the PTS naming conventions are used for Python language entities:

Entity Convention Example
Package (directory) All lowercase letters, no separators storedtable
Module (file) All lowercase letters, no separators skirtsimulation
Class Camel case starting with upper case letter SkiFile
Function Camel case starting with lower case letter performSimulation()
-> getter name of property backgroundColor()
-> setter set + capitalized name of property setBackgroundColor()
Variable Camel case starting with lower case letter; or all lowercase letters, no separators nx, fluxDensity
Data member Leading underscore plus variable name (all data members are private) _nx, _fluxDensity

## Organizing package functionality

Each PTS package (a directory, see Packages, modules and directories) exposes all public functions and classes (i.e. those intended for use outside of the package) at the package level. The functionality is implemented in various modules (python source files) residing inside the package. The initialization file for each package places the public names into the package namespace using explicit imports.

## Importing packages

Default style for importing external packages (including standard-library packages):

import some.package           # each reference must include full package name


External packages imported with a local name:

import astropy.constants as const
import astropy.io.fits as fits
import astropy.units as u
import lxml.etree as etree
import matplotlib.pyplot as plt
import numpy as np


Importing other PTS packages (or same package from within do subdirectory):

import pts.admin as adm
import pts.band as bnd
import pts.do as do
import pts.simulation as sm
import pts.storedtable as stab
import pts.utils as ut
import pts.visual as vis


Importing symbols from within the same package, including initialization file:

from .module import name      # default style is to use explicit import
from .module import *         # exceptional style, for example in conversionspec.py


## External dependencies

Any PTS code may depend on any of the standard Python 3.7 packages without further mention. In addition, some of the PTS facilities may require non-standard Python packages to be installed. Developers are urged to avoid additional dependencies where possible, and to use only packages that are readily available from the common distribution channels.

See Required Python packages for a list of the required non-standard packages at the time of writing. To obtain a list of the current package dependencies, make sure that PTS is properly installed and enter the following terminal command:

pts list_dependencies


# Building the documentation

The PTS reference documentation is generated from the Python source files (and from the extra files in the docs directory) by Doxygen. For information on how to install this free application, refer to the SKIRT installation guide (section "Installing the documentation generator" on page "Develop using Qt Creator").

When you add or adjust code, it is important to provide proper documentation in the header file, in Doxygen format. To verify that everything looks as intended, especially when including formulas in mathematical notation, you should build the HTML documentation and open the resulting page(s) in a web browser.

The git directory contains a shell script for building the documentation. The script is designed for use on Mac OS X and will need to be adjusted for use on other systems. For example, the absolute path to the Doxygen executable will need to be updated, and the html.doxygen parameter file may need some tweaking as well.

Before invoking the script for the first time, you may need to make it executable as follows:

cd ~/PTS/git
chmod +rx makeHTML.sh


To build the HTML reference documentation, enter:

cd ~/PTS/git
./makeHTML.sh


The resulting HTML files are placed in the html directory next to (i.e. at the same level as) the git directory. As usual, the file index.html provides the starting point for browsing.

The source text for the PTS installation, user and developer guides is maintained in a different repository. For more information about how to edit and publish this documentation, refer to the SKIRT developer guide (section "Additional documentation" on page "Building the documentation")

# Contributing to PTS

We invite your contributions to PTS and to the SKIRT project in general. A contribution can take many forms, from asking a question to implementing a new feature. More information on how to contribute can be found here: