Using the standalone executable#
by David A. Minton
For many users, it may be desirable to separate the generation of initial conditions from the actual simulation. In such cases,
users may find it useful to use the standalone executable that is built with Swiftest. The standalone executable is a command-line
tool that can be used to run simulations from a set of initial conditions and a configuration file. The configuration file is a
simple text file that contains the parameters for the simulation, such as the total time of the simulation, the time step size, and
the output cadence. By default this file is called param.in. Running the executable is similar to using the older
Swift and Swifter packages.
Create a basic solar system simulation#
First we will create a basic solar system simulation
In [1]: import swiftest
In [2]: sim = swiftest.Simulation(tstop=1.0, dt=0.01, tstep_out=0.1)
Reading Swiftest file /home/docs/checkouts/readthedocs.org/user_builds/swiftest/checkouts/latest/docs/simdata/param.in
codename Swiftest
gmtiny 0.0 DU^3 / TU^2
mtiny 0.0 MU
t0 0.0 TU
tstart 0.0 TU
istep_out 1
dump_cadence 1
init_cond_file_name init_cond.nc
init_cond_file_type NETCDF_DOUBLE
init_cond_format XV
output_file_type NETCDF_DOUBLE
output_file_name data.nc
output_format XVEL
restart REPLACE
rmin 0.004650467260962157 DU
rmax 10000.0 DU
qmin_coord HELIO
close_encounter_check True
rhill_present False
extra_force False
general_relativity True
collision_model FRAGGLE
minimum_fragment_gmass 0.0 DU^3 / TU^2
minimum_fragment_mass 0.0 MU
minimum_fragment_gmass 0.0 DU^3 / TU^2
minimum_fragment_mass 0.0 MU
nfrag_reduction 30.0
rotation True
compute_conservation_values True
interaction_loops TRIANGULAR
encounter_check_loops TRIANGULAR
encounter_save NONE
codename Swiftest
codename Swiftest
tstop 1.0 TU
dt 0.01 TU
istep_out 10
tstep_out 0.1 TU
In [3]: sim.add_solar_system_body(["Sun","Mercury","Venus","Earth","Mars","Jupiter","Saturn","Uranus","Neptune"])
Adding solar system bodies by name: Sun, Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune
Creating the Sun as a central body
Fetching ephemerides data for Mercury from JPL/Horizons
Found matching body: Mercury Barycenter (1)
Alternate matching bodies:
Mercury (199)
Found ephemerides data for Mercury Barycenter (1) from JPL/Horizons
Physical properties found for Mercury Barycenter (199)
Fetching ephemerides data for Venus from JPL/Horizons
Found matching body: Venus Barycenter (2)
Alternate matching bodies:
Venus (299)
Found ephemerides data for Venus Barycenter (2) from JPL/Horizons
Physical properties found for Venus Barycenter (299)
Fetching ephemerides data for Earth from JPL/Horizons
Found matching body: Earth-Moon Barycenter (3)
Alternate matching bodies:
Earth (399)
Found ephemerides data for Earth-Moon Barycenter (3) from JPL/Horizons
Found matching body: Earth (399) (399)
Physical properties found for Earth (399)
Combining mass of Earth and the Moon
Found matching body: Moon (301) (301)
Physical properties found for Moon (301)
Fetching ephemerides data for Mars from JPL/Horizons
Found matching body: Mars Barycenter (4)
Alternate matching bodies:
Mars (499)
Found ephemerides data for Mars Barycenter (4) from JPL/Horizons
Found matching body: Mars (499) (499)
Physical properties found for Mars (499)
Fetching ephemerides data for Jupiter from JPL/Horizons
Found matching body: Jupiter Barycenter (5)
Alternate matching bodies:
Jupiter (599)
Found ephemerides data for Jupiter Barycenter (5) from JPL/Horizons
Found matching body: Jupiter (599) (599)
Physical properties found for Jupiter (599)
Fetching ephemerides data for Saturn from JPL/Horizons
Found matching body: Saturn Barycenter (6)
Alternate matching bodies:
Saturn (699)
Found ephemerides data for Saturn Barycenter (6) from JPL/Horizons
Found matching body: Saturn (699) (699)
Physical properties found for Saturn (699)
Fetching ephemerides data for Uranus from JPL/Horizons
Found matching body: Uranus Barycenter (7)
Alternate matching bodies:
Uranus (799)
Found ephemerides data for Uranus Barycenter (7) from JPL/Horizons
Found matching body: Uranus (799) (799)
Physical properties found for Uranus (799)
Fetching ephemerides data for Neptune from JPL/Horizons
Found matching body: Neptune Barycenter (8)
Alternate matching bodies:
Neptune (899)
Found ephemerides data for Neptune Barycenter (8) from JPL/Horizons
Found matching body: Neptune (899) (899)
Physical properties found for Neptune (899)
rmin 0.004650467260962157 DU
Writing initial conditions to file /home/docs/checkouts/readthedocs.org/user_builds/swiftest/checkouts/latest/docs/simdata/init_cond.nc
Writing parameter inputs to file /home/docs/checkouts/readthedocs.org/user_builds/swiftest/checkouts/latest/docs/simdata/param.in
Instead of running it, we will simply save the current state of the system to a file.
In [4]: sim.save()
Writing initial conditions to file /home/docs/checkouts/readthedocs.org/user_builds/swiftest/checkouts/latest/docs/simdata/init_cond.nc
Writing parameter inputs to file /home/docs/checkouts/readthedocs.org/user_builds/swiftest/checkouts/latest/docs/simdata/param.in
Outputs are stored in the ./simdata directory by default. There should be two files created: param.in and init_cond.nc.
These files contain the parameters for the simulation and the initial conditions of the simulation. Now to run the simulation
from the terminal, simply navigated to the simdata directory and run the executable.
In [5]: %%bash
...: cd simdata
...: swiftest whm param.in classic
...:
RESTART F
T0 0.0000000000000000000E+00
TSTART 0.0000000000000000000E+00
TSTOP 1.0000000000000000000E+00
DT 1.0000000000000000208E-02
IN_TYPE NETCDF_DOUBLE
NC_IN init_cond.nc
IN_FORM XV
DUMP_CADENCE 1
ISTEP_OUT 10
BIN_OUT data.nc
OUT_TYPE NETCDF_DOUBLE
OUT_FORM XVEL
OUT_STAT APPEND
CHK_RMIN 4.6504672609621574078E-03
CHK_RMAX 1.0000000000000000000E+04
CHK_EJECT 1.0000000000000000000E+04
CHK_QMIN 4.6504672609621574078E-03
CHK_QMIN_COORD HELIO
CHK_QMIN_RANGE 4.6504672609621574078E-03 1.0000000000000000000E+04
MU2KG 1.9884098706980509592E+30
TU2S 3.1557600000000000000E+07
DU2M 1.4959787070000000000E+11
RHILL_PRESENT F
EXTRA_FORCE F
CHK_CLOSE T
ENERGY T
GR T
ROTATION T
TIDES F
INTERACTION_LOOPS TRIANGULAR
ENCOUNTER_CHECK_PLPL TRIANGULAR
ENCOUNTER_CHECK_PLTP TRIANGULAR
ENCOUNTER_SAVE NONE
COARRAY F
FIRSTENERGY T
FIRSTKICK T
GMTINY 0.0000000000000000000E+00
MIN_GMFRAG 0.0000000000000000000E+00
COLLISION_MODEL FRAGGLE
NFRAG_REDUCTION 3.0000000000000000000E+01
SEED 33 -2142695598 -23609994 2049636370 -2137331188 -1587810956 -982921141 240637314 -549457304 -255026469 498283291 1434921829 -690039998 1773938171 1373893138 -492079728 -1388299306 -250363072 206836198 -976832877 -1423984409 -206031014 -1263893933 -1826324524 112181911 -738146897 545450591 908001426 1106198608 -549066657 454487170 -524129880 -1924769704 0
OpenMP parameters:
------------------
Number of threads = 1
*************** Swiftest 2025.10.0 start Wisdom-Holman Method ***************
Time = 0.00000E+00; fraction done = 0.000; Number of active pl, tp = 8, 0
Integration steps: Total wall time: 1.10640E-04; Interval wall time: 9.31000E-05; Interval wall time/step: 9.31000E-06
Time = 1.00000E-01; fraction done = 0.100; Number of active pl, tp = 8, 0
Integration steps: Total wall time: 1.73399E-01; Interval wall time: 7.99500E-05; Interval wall time/step: 7.99500E-06
Time = 2.00000E-01; fraction done = 0.200; Number of active pl, tp = 8, 0
Integration steps: Total wall time: 2.54538E-01; Interval wall time: 5.69300E-05; Interval wall time/step: 5.69300E-06
Time = 3.00000E-01; fraction done = 0.300; Number of active pl, tp = 8, 0
Integration steps: Total wall time: 3.43436E-01; Interval wall time: 5.65000E-05; Interval wall time/step: 5.65000E-06
Time = 4.00000E-01; fraction done = 0.400; Number of active pl, tp = 8, 0
Integration steps: Total wall time: 4.37845E-01; Interval wall time: 5.80100E-05; Interval wall time/step: 5.80100E-06
Time = 5.00000E-01; fraction done = 0.500; Number of active pl, tp = 8, 0
Integration steps: Total wall time: 5.32121E-01; Interval wall time: 5.56910E-05; Interval wall time/step: 5.56910E-06
Time = 6.00000E-01; fraction done = 0.600; Number of active pl, tp = 8, 0
Integration steps: Total wall time: 6.25973E-01; Interval wall time: 5.72600E-05; Interval wall time/step: 5.72600E-06
Time = 7.00000E-01; fraction done = 0.700; Number of active pl, tp = 8, 0
Integration steps: Total wall time: 7.19950E-01; Interval wall time: 5.86700E-05; Interval wall time/step: 5.86700E-06
Time = 8.00000E-01; fraction done = 0.800; Number of active pl, tp = 8, 0
Integration steps: Total wall time: 8.14402E-01; Interval wall time: 5.54600E-05; Interval wall time/step: 5.54600E-06
Time = 9.00000E-01; fraction done = 0.900; Number of active pl, tp = 8, 0
Integration steps: Total wall time: 9.08205E-01; Interval wall time: 5.79910E-05; Interval wall time/step: 5.79910E-06
Time = 1.00000E+00; fraction done = 1.000; Number of active pl, tp = 8, 0
Time = 1.00000E+00; fraction done = 1.000; Number of active pl, tp = 8, 0
*************** Swiftest stop Wisdom-Holman Method ***************
Normal termination of Swiftest (version 2025.10.0)
-----------------------------------------------------
This will execute the simulation using the basic Wisdom-Holman symplectic map integrator and report the progress to the terminal.
For a more streamlined output that shows a progress bar and saves the terminal output to a file called swiftest.log you can instead run
In [6]: %%bash
...: cd simdata
...: swiftest whm param.in progress
...:
OpenMP: Number of threads = 1
[ ]
[ ] Time = 0.00000E+00 of 1.00000E+00
[ # ] Time = 1.00000E-01 of 1.00000E+00
[ # # ] Time = 2.00000E-01 of 1.00000E+00
[ # # # ] Time = 3.00000E-01 of 1.00000E+00
[ # # # # ] Time = 4.00000E-01 of 1.00000E+00
[ # # # # # ] Time = 5.00000E-01 of 1.00000E+00
[ # # # # # # ] Time = 6.00000E-01 of 1.00000E+00
[ # # # # # # # ] Time = 7.00000E-01 of 1.00000E+00
[ # # # # # # # # ] Time = 8.00000E-01 of 1.00000E+00
[ # # # # # # # # # ] Time = 9.00000E-01 of 1.00000E+00
[ # # # # # # # # # #] Time = 1.00000E+00 of 1.00000E+00
[ # # # # # # # # # #] Time = 1.00000E+00 of 1.00000E+00
Normal termination of Swiftest (version 2025.10.0)
-----------------------------------------------------
The default output style is progress, so this is identical:
$ swiftest whm param.in
If you prefer no output be printed on the terminal at all, you can use the quiet style:
$ swiftest whm param.in quiet
Once the simulation is done, the results can be read in from Python
In [7]: import swiftest
In [8]: sim = swiftest.Simulation(read_data=True)
Reading Swiftest file /home/docs/checkouts/readthedocs.org/user_builds/swiftest/checkouts/latest/docs/simdata/param.in
codename Swiftest
gmtiny 0.0 DU^3 / TU^2
mtiny 0.0 MU
t0 0.0 TU
tstart 0.0 TU
tstop 1.0 TU
dt 0.01 TU
istep_out 10
dump_cadence 1
tstep_out 0.1 TU
init_cond_file_name init_cond.nc
init_cond_file_type NETCDF_DOUBLE
init_cond_format XV
output_file_type NETCDF_DOUBLE
output_file_name data.nc
output_format XVEL
restart REPLACE
rmin 0.004650467260962157 DU
rmax 10000.0 DU
qmin_coord HELIO
close_encounter_check True
rhill_present False
extra_force False
general_relativity True
collision_model FRAGGLE
minimum_fragment_gmass 0.0 DU^3 / TU^2
minimum_fragment_mass 0.0 MU
minimum_fragment_gmass 0.0 DU^3 / TU^2
minimum_fragment_mass 0.0 MU
nfrag_reduction 30.0
rotation True
compute_conservation_values True
interaction_loops TRIANGULAR
encounter_check_loops TRIANGULAR
encounter_save NONE
codename Swiftest
Reading Swiftest file /home/docs/checkouts/readthedocs.org/user_builds/swiftest/checkouts/latest/docs/simdata/param.in
codename Swiftest
gmtiny 0.0 DU^3 / TU^2
mtiny 0.0 MU
t0 0.0 TU
tstart 0.0 TU
tstop 1.0 TU
dt 0.01 TU
istep_out 10
dump_cadence 1
tstep_out 0.1 TU
init_cond_file_name init_cond.nc
init_cond_file_type NETCDF_DOUBLE
init_cond_format XV
output_file_type NETCDF_DOUBLE
output_file_name data.nc
output_format XVEL
restart REPLACE
rmin 0.004650467260962157 DU
rmax 10000.0 DU
qmin_coord HELIO
close_encounter_check True
rhill_present False
extra_force False
general_relativity True
collision_model FRAGGLE
minimum_fragment_gmass 0.0 DU^3 / TU^2
minimum_fragment_mass 0.0 MU
minimum_fragment_gmass 0.0 DU^3 / TU^2
minimum_fragment_mass 0.0 MU
nfrag_reduction 30.0
rotation True
compute_conservation_values True
interaction_loops TRIANGULAR
encounter_check_loops TRIANGULAR
encounter_save NONE
Reading initial conditions file as .init_cond
Creating Dataset from NetCDF file
Successfully converted 1 output frames.
Creating Dataset from NetCDF file
Successfully converted 11 output frames.
Swiftest simulation data stored as xarray Dataset .data
Reading initial conditions file as .init_cond
Creating Dataset from NetCDF file
Successfully converted 1 output frames.
Reading collisions history file as .collisions
Finished reading Swiftest dataset files.
Passing the argument read_data=True informs the Simulation class to read in a pre-existing data file rather than starting a new simulation.