Getting Started

Swiftest is a re-write of the Swifter software package that incorporates modern programming techniques and performance improvements. Swiftest contains the following numerical integrators:

• Wisdom-Holman Mapping (WHM) - A symplectic n-body mapping method. See Wisdom & Holman (1991).

• Regularized Mixed Variable Symplectic (RMVS) - An extension of WHM that is capable of handling close encounters between test particles and massive bodies. See Levison & Duncan (1994).

• Democratic Heliocentric (HELIO) - A symplectic integrator that uses the democratic heliocentric coordinate frame. See

• Duncan, Levison, & Lee (1998).

• Symplectic Massive Body Algorithm (SyMBA) - An extension of HELIO that is capable of handling close encounters between massive bodies. See Duncan, Levison, & Lee (1998).

Swiftest also includes the collisional fragmentation algorithm Fraggle, which can be used to model collisional fragmentation when using the SyMBA integrator. Fraggle is designed to resolve collisions between massive bodies by determining the collisional regime, derived from the work of Leinhardt & Stewart (2012), and generating the appropriate mass distribution of fragments. Swiftest fully incorporates collisional fragments into the gravitational system, evolving these new bodies along with pre-existing bodies, including their growth and any future fragmentation events in which they are involved.

Swiftest is written in Modern Fortran and is designed to be run from Python. The Python package provides a set of tools for generating initial conditions, running simulations, and processing output data. Swiftest can also be run from the command line using the swiftest executable, provided that initial conditions and configuration files are available in the path.

Installation

For most users, installing swiftest can be done via pip using the command

pip install swiftest

This will install the swiftest Python package, which can be incorporated into Python projects using import swiftest. It also will install a standalone executable called swiftest, which can execute simulations from the command line, provided that initial conditions and configuration files are available in the path.

Building Swiftest from source

If you wish to build Swiftest from source, which in some cases can lead to some performance improvements over the pre-built wheels, you can do so by following the instructions below. This will require a Fortran compiler, CMake, and the NetCDF and HDF5 libraries to be installed on your system. The instructions below are for building Swiftest on a Linux or MacOS system. Installing on Windows is similar when using the MSYS2 platform.

You can obtain the latest version of Swiftest from the GitHub repository , or from from a releases as a tarball.

Required Dependencies

Swiftest output files are stored in the NetCDF file format. This takes the place of the flat binary output file included in Swifter (and its predecessor Swift). The NetCDF output format is compatible with Python, Java, and other languages that can be used to process and analyze simulation data. Details on installing NetCDF and the NetCDF Fortran Library can be found on the Unidata website. NetCDF is built on HDF5 and it is necessary to install HDF and HDF5 as well. Details on installing HDF and HDF5 can be found on the HDF Group website.

Parallelization in Swiftest is done with OpenMP. Version 3.1.4 or higher is necessary to make use of parallelization in Swiftest. If Swiftest is only to be run in serial, this package is not necessary. See the OpenMP website for more details and installation instructions.

Central body gravity is modeled using the SHTOOLS library <https://shtools.github.io/SHTOOLS/>. It is necessary to build and install SHTOOLS before building Swiftest. Optionally the pySHTOOLS package may also be installed in order to use the tools to compute spherical harmonics coefficients for the central body when generating initial conditions, but is not required.

Swiftest is written in Modern Fortran and must be compiled using an appropriate compiler. We recommend the Intel Fortran Compiler Classic (ifort) version 19.0 or higher. For details on installing ifort, see the Intel installation documentation. The GCC/GNU Fortran Compiler (gfortran) version 9 or higher is also compatible. For details on installing gfortran, see the GNU Fortran documentation. As of the time of writing, the ifx compiler is not supported.

Installing Dependencies using the Buildscripts

The Swiftest project contains a set of build scripts that can be used to help build the dependencies required to build Swiftest. These scripts are used to build the official Swiftest Python wheels using cibuildwheel. In addition, we have also included a pair of scripts that will set environment variables for Linux or MacOS.

For Linux, ensure that the following dependencies are installed

• doxygen

• libxml2 (development version)

• libcurl (development version)

• fftw (static version)

• openblas (development version)

• lapack (development version)

• cmake

• ninja-build

• gfortran

• graphviz

These dependencies can be installed on a RedHat based system by running the following commands from the command line.

sudo yum install epel-release
sudo yum install doxygen libxml2-devel libcurl-devel fftw-static openblas-static openmpi-devel lapack-devel cmake ninja-build gcc-gfortran openmpi-devel graphviz

On a Debian based system, the dependencies can be installed by running the following commands from the command line

sudo apt-get install doxygen libxml2-dev libcurl4-openssl-dev libfftw3-dev libopenblas-dev liblapack-dev cmake ninja-build gfortran libopenmpi-dev graphviz

On a MacOS system, be sure homebrew is installed.

brew install coreutils

The most critical dependency needed by Swiftest is netcdf-fortran. However, netcdf-fortran requires netcdf (which requires HDF5, and so on). netcdf-fortran must be compiled using the same compiler that builds Swiftest in order that the .mod files are compatible. On MacOS systems, the version of netcdf-fortran available in Homebrew satisfies this condition, as long as you also use gfortran from homebrew. Therefore on MacOS systems, you can simply use the Homebrew versions of things:

brew install gfortran netcdf-fortran

However, if you need to build netcdf-fortran (and its chain of dependencies) manually, we provide a comprehensive dependency-building script called build_dependencies.sh. We also provide a script that can be used to set environment variables prior to building the dependencies called set_environment.sh. Building the dependencies can be done by running the following command from the command line

. buildscripts/set_environment.sh
buildscripts/build_dependencies.sh

Note that the above scripts will use gfortran to build the dependencies. If you wish to use the Intel Fortran Compiler, you will need to modify the build scripts to use the Intel Fortran Compiler.

Building the Swiftest Python Package and Executable

Once dependencies are installed, you can install the Swiftest Python package and the Swiftest executable into an active Python environment by running the following command from the command line:

pip install .

Or, alternatively, if you wish to install an editable version, be sure that you have the build dependencies installed in your Python environment:

pip install scikit-build-core cython numpy setuptools setuptools_scm

Then build and install the editable version:

pip install --no-build-isolation -ve .

You can test your installation using pytest. Be sure it is first installed into your Python environment:

pip install pytest

Then run the tests from the topmost directory in your Swiftest repository:

python -m pytest tests

Building the executable using CMake

Although Swiftest is designed to be run from Python, it is also possible to run Swiftest simulations from the command line using the swiftest executable, provided it has an initial conditions file and a configuration parameter file, which are typically generated using the Python package.

The swiftest is compiled through CMake. Compiling with CMake has a number of benefits that provide a streamlined experience for the Swiftest user and developer. At compilation, CMake will automatically select the set of flags that are compatible with the local compiler. CMake also allows a Swiftest developer to re-compile only the files that have been edited, instead of requiring the developer to re-compile the entire Swiftest program. Please visit the CMake website for more information on how to install CMake.

As mentioned in the System Requirements section, Swiftest requires the NetCDF and NetCDF Fortran libraries to be installed prior to compilation. If the libraries are installed in the standard library location on your machine, CMake should be able to find the libraries without specifying the path. However, if CMake struggles to find the NetCDF libraries, there are two ways to set the path to these libraries.

1. Create an environment variable called NETCDF_FORTRAN_HOME that contains the path to the location where the libraries are installed

2. Set the path at the build step using -CMAKE_PREFIX_PATH=/path/to/netcdf/

CMake allows the user to specify a set of compiler flags to use during compilation. We define five sets of compiler flags: release, testing, profile, math, and debug. To view and/or edit the flags included in each set, see swiftest/cmake/Modules/SetFortranFlags.cmake.

As a general rule, the release flags are fully optimized and best used when running Swiftest with the goal of generating results. This is the default set of flags. When making changes to the Swiftest source code, it is best to compile Swiftest using the debug set of flags. You may also define your own set of compiler flags.

Navigate to the topmost directory in your Swiftest repository. It is best practice to create a build directory in your topmost directory from which you will compile Swiftest. This way, temporary CMake files will not clutter up the swiftest/src/ sub-directories. The commands to build the source code into a build directory and compile Swiftest are

cmake -B build -S . -G Ninja
cmake --build build -j8

You may omit the -G Ninja flag if you do not have the Ninja build system installed. The -j8 flag is used to specify the number of threads to use during compilation.

The CMake Fortran template comes with a script that can be used to clean out any build artifacts and start from scratch

cmake -P distclean.cmake

The Swiftest CMake configuration comes with several customization options:

Option	CMake command	Default value
Build type	-DCMAKE_BUILD_TYPE=[RELEASE|DEBUG|TESTING|PROFILE]	RELEASE
Enable/Disable OpenMP support	-DUSE_OPENMP=[ON|OFF]	ON
Enable/Disable SIMD directives	-DUSE_SIMD=[ON|OFF]	ON
Enable/Disable Coarray support (experimental)	-DUSE_COARRAY=[ON|OFF]	OFF
Set Fortran compiler path	-DCMAKE_Fortran_COMPILER=/path/to/fortran/compiler	${FC}
Set path to make program	-DCMAKE_MAKE_PROGRAM=/path/to/make	${PATH}
Enable/Disable shared libraries (Intel only)	-DBUILD_SHARED_LIBS=[ON|OFF]	ON
Add additional include path	-DCMAKE_Fortran_FLAGS=”-I/path/to/libraries”	None
Install prefix	-DCMAKE_INSTALL_PREFIX=[“/path/to/install”|]	/usr/local

To see a list of all possible options available to CMake

cmake -B build -S . -LA

The Swiftest executable, called swiftest as well as the shared library, either libswiftest.so or libswiftest.dylib, depending on your platform, should now be created in the build/bin/ directory. You can also install the it into your system by running

cmake --install build

You may need to run the above command as root or with sudo if you are installing into a system directory.

Passing CMake arguments to pip

If you are installing Swiftest using pip and wish to pass CMake arguments, you can do so by using the --config-settings=cmake.args option. For example, to set a custom directory location for user-defined forces in an editable install in debug mode, you could do this:

pip install --config-settings=cmake.build-type="DEBUG" --config-settings=cmake.args="-DSWIFTEST_USER_DIR='/full/path/to/folder'" --no-build-isolation -ve .