The SKIRT project
advanced radiative transfer for astrophysics
SKIRT project directory structure

An administator's SKIRT project directory must be complete and have the exact structure described below. This is important because the administator shell scripts and PTS commands rely on this structure. For example, the contents of the SKIRT web site is derived from sources and data spread out across many of the project's subdirectories.

The SKIRT project directory

SKIRT
    Backup
    Benchmark9
    Functional9
    PTS9
    Resources9
    ResourcesC
    SKIRT9
    Web9

The top level directory for the SKIRT project is called SKIRT and resides directly in the administator's home folder, i.e. at the highest level. Its subdirectories, shown above in alphabetical order, are described in the following sections.

When setting up this directory structure:

  • The SKIRT9, PTS9, and Web9 directory contents should be cloned from the corresponding GitHub repositories in the manner described below for each directory (not following the installation instructions for a regular user).
  • The contents of the other directories must be obtained from a current backup created by another administrator.
Note
There are currently no provisions for synchronizing the contents of the non-GitHub directories between multiple administrators/computers. The most straighforward manual synchronization technique is to ensure that (1) just a single administrator is making changes at any one time, and (2) backups of the most recent version are exchanged when transitioning between administrators.
Do not include directories in this structure with names such as SKIRT or PTS. Some PTS commands may look in those directories first (for example, for locating a skirt executable) to accommodate regular users who don't include the 9 suffix. But this will confuse the operation of the administrator procedures.

Directories obtained from GitHub

The SKIRT9 and PTS9 repositories follow the GitHub fork and pull workflow model. This means you should never push any changes directly to these repositories. Let us repeat this. You should never push any changes directly to the SKIRT9 and PTS9 repositories. Instead, contributors including administrators push suggested changes to their own fork and initiate a pull request. After approval, an administrator then merges the pull request to the master branch in the main SKIRT9 or PTS9 repository. For more information, see The GitHub workflow for the SKIRT project.

The Web9 repository currently does not follow this workflow model because the administrator is the sole contributor. In other words, until this policy is modified, you can push any updates directly to the Web9 repository.

SKIRT9

SKIRT9
    git
    html
    release
    resources

This directory contains a local copy of the SKIRT9 repository, plus build and resource directories. As an administrator, your local copy of the SKIRT code must be connected to both the main SKIRT9 repository and your own fork of this repository. This is accomplished as follows.

  • If you have not already done so, configure your local git so that your identity will be attached to your commits (include the quotation marks and replace USERNAME by your GitHub user name and name@domain.com by your email address):

    $ git config --global user.name "USERNAME"
$ git config --global user.email "name@domain.com"
  • If you have not already done so, fork the SKIRT9 repository (a fork is a personal copy of a repository hosted on GitHub). On the GitHub web site, login under your personal account, navigate to the page for the SKIRT9 repository, click the "Fork" dropdown and select "Create a new fork".
  • Back on your computer, verify whether your local copy of the SKIRT9 directory, if present, contains any code changes or other information you wish to retain. If so, make a backup copy. Then remove the complete contents of the SKIRT9 directory.

  • Clone your personal fork to a local copy on your computer (replace USERNAME by your GitHub user name):

    $ cd ~/SKIRT
$ mkdir SKIRT9
$ cd SKIRT9
$ git clone https://github.com/USERNAME/SKIRT9.git git
$ cd git
$ git remote -v
origin https://github.com/USERNAME/SKIRT9.git (fetch)
origin https://github.com/USERNAME/SKIRT9.git (push)

  • Establish the main SKIRT9 repository as the "upstream" respository for your local copy:

    $ git remote add upstream https://github.com/SKIRT/SKIRT9.git
$ git remote -v
origin https://github.com/petercamps/SKIRT9.git (fetch)
origin https://github.com/petercamps/SKIRT9.git (push)
upstream https://github.com/SKIRT/SKIRT9.git (fetch)
upstream https://github.com/SKIRT/SKIRT9.git (push)

  • Download and install all SKIRT resource packs (enter "y" in response to all questions):

    $ ./downloadResources.sh
...
  • Using Qt Creator, configure the SKIRT build options to include doxstyle and MakeUp, and build the project. For more information, see Configure and build the code.

  • If you have not already done so, add or adjust the location of the skirt executable in your PATH. For example, add the following line to your login script:

    export PATH="${HOME}/SKIRT/SKIRT9/release/SKIRT/main:${PATH}"

For more information, see:

PTS9

PTS9
    html
    pts

This directory essentially contains a local copy of the PTS9 repository. As for the SKIRT code, your local copy of the PTS code must be connected to both the main PTS9 repository and your own fork of this repository. A key difference is that PTS must be cloned into a pts subdirectory instead of a git subdirectory.

  • If you have not already done so, configure your local git so that your identity will be attached to your commits (see previous section for instructions).
  • If you have not already done so, fork the PTS9 repository (see previous section for instructions).
  • Back on your computer, verify whether your local copy of the PTS9 directory, if present, contains any code changes or other information you wish to retain. If so, make a backup copy. Then remove the complete contents of the PTS9 directory.

  • Clone your personal fork to a local copy on your computer, and establish the main PTS9 repository as the "upstream" respository for your local copy (replace USERNAME by your GitHub user name):

    $ cd ~/SKIRT
$ mkdir PTS9
$ cd PTS9
$ git clone https://github.com/USERNAME/PTS9.git pts
$ cd pts
$ git remote add upstream https://github.com/SKIRT/PTS9.git

  • If you have not already done so, provide or adjust the location of the PTS modules in your login script. For example:

    export PYTHONPATH=~/SKIRT/PTS9
alias pts="python -m pts.do"

For more information, see:

Web9

Web9
    git
    html
    public
    stage

This directory contains a local copy of the Web9 repository, plus directories for building and publishing the SKIRT web site. The Web9 repository contains the source text (and some python code) for a significant fraction of the web site, including the community section and the installation, user, developer, and administration guides. On the other hand, the reference documentation is derived directly from the source code residing in the SKIRT9 and PTS9 directories.

The Web9 repository currently does not follow the GitHub workflow model, so you can clone the repository in a straightforward manner:

$ cd ~/SKIRT
$ mkdir Web9
$ cd Web9
$ git clone https://github.com/SKIRT/Web9.git git
$ cd git
$ git remote -v
origin https://github.com/SKIRT/Web9.git (fetch)
origin https://github.com/SKIRT/Web9.git (push)

For more information, see:

Directories obtained from administrator backups

Backup

Backup
    create_backup.txt
    Backup--2025-07-12--10-09-27

This directory contains information related to backing up the SKIRT project. Specifically:

  • the create_backup.txt text file provides manually edited instructions for the PTS create_backup command, essentially describing the type of information residing in each of the SKIRT project subdirectories.
  • The Backup--* directories, if present, contain backup ZIP archives created by the PTS create_backup command. After moving the backups in these directories to an off-line backup location, the local copies can be deleted.

For more information, see:

Benchmark9

Benchmark9
    _ReadMe.txt
    1997_Ivezic
    2002_vanZadelhoff_1
    ...
    XRAY3_ISMDUST
    XRAY4_RXTORUS

This directory contains all documentation, runtime specifications, and reference results for the formal benchmarks comparing SKIRT output to published results. For more information, see:

Functional9

Functional9
    _testreports
    Cosmology
    Emission
    ...
    Units
    WavelengthDistributions
    WavelengthGrids

This directory contains the specifications and reference results for over 800 functional tests that can be run and verified automatically to avoid regression after each update or addition to the SKIRT code. For more information, see:

Resources9

Resources9
    OriginalData
    Publish
    StoredTables

This directory contains all data related to the resources used by the SKIRT code. This includes the orginal data obtained from a third party where applicable, the corresponding "stored table" files consumed by SKIRT, the resource packs to be made available for public download, the specifications for converting between these formats, and the procedures for publishing the resource packs to the SKIRT data file server. For more information, see:

ResourcesC

ResourcesC
    Benchmarks
    DustPediaData
    Publications
    Publish
    Tutorials

This directory contains all data files referenced from the web site and published on the SKIRT data file server (other than the resource packs discussed in the previous section). This includes example ski files referenced from benchmark descriptions or tutorials, and a copy of papers listed in the web site's publications section. For more information, see:

The SKIRT project -- advanced radiative transfer for astrophysics © Astronomical Observatory, Ghent University