Swiftest API reference

This section of the documentation provides a detailed reference for the Production classes in the Swiftest project.

Simulation

The Simulation class is the main class for the Swiftest project.

Creating a Simulation

Simulation([simdir, param_file, read_param, ...])

Defines the basic Swift/Swifter/Swiftest simulation object.

Running a Simulation

Simulation.run([dask])

Runs a Swiftest integration.

Setting Simulation Parameters

Simulation.set_parameter(**kwargs)	Setter for all possible parameters.
Simulation.set_simulation_time([t0, tstart, ...])	Set the parameters that control how a simulation is run, such as start and stop time, step size, and the cadence of output to both the screen and to file.
Simulation.set_integrator([codename, ...])	Sets the integrator to be used when running a simulation.
Simulation.set_feature([...])	Turns on or off various features of a simulation.
Simulation.set_init_cond_files([...])	Sets the initial condition file parameters in the parameters dictionary.
Simulation.set_output_files([...])	Sets the output file parameters in the parameter dictionary.
Simulation.set_unit_system([MU, DU, TU, ...])	Setter for setting the unit conversion between one of the standard sets.
Simulation.set_distance_range([rmin, rmax, ...])	Sets the minimum and maximum distances of the simulation.

Retrieving Simulation Parameters

Simulation.get_parameter(**kwargs)	Setter for all possible parameters.
Simulation.get_simulation_time([arg_list])	Returns a subset of the parameter dictionary containing the current simulation time parameters.
Simulation.get_integrator([arg_list])	Returns a subset of the parameter dictionary containing the current values of the distance range parameters.
Simulation.get_feature([arg_list])	Returns a subset of the parameter dictionary containing the current value of the feature boolean values.
Simulation.get_init_cond_files([arg_list])	Returns a subset of the parameter dictionary containing the current initial condition file parameters.
Simulation.get_output_files([arg_list])	Returns a subset of the parameter dictionary containing the current output file parameters.
Simulation.get_unit_system([arg_list])	Returns a subset of the parameter dictionary containing the current simulation unit system.
Simulation.get_distance_range([arg_list])	Returns a subset of the parameter dictionary containing the current values of the distance range parameters.
Simulation.get_ephemeris_date([arg_list])	Prints the current value of the ephemeris date.

Adding Bodies to a Simulation

Simulation.add_solar_system_body([name, ...])	Adds a solar system body to an existing simulation Dataset from the JPL Horizons ephemeris service.
Simulation.add_body([name, a, e, inc, ...])	Adds a body (test particle or massive body) to the internal Dataset given a set of either orbital elements or cartesian state vectors.
Simulation.modify_body([name, id, a, e, ...])	Modifies an existing body in the internal Dataset given a new value of either the orbital elements or cartesian state vectors, or the physical property of the body (mass, radius, etc).
Simulation.remove_body([name, id])	Removes a body (test particle or massive body) from the internal Dataset.

File Input and Output

Simulation.read_param([param_file, codename])	Reads in an input parameter file and stores the values in the param dictionary.
Simulation.write_param([codename, ...])	Writes to a param.in file and determines whether the output format needs to be converted between Swift/Swifter/Swiftest.
Simulation.read_encounter_file([dask])	Reads in an encounter history file and stores it as a SwiftestDataset in the encounters instance variable.
Simulation.read_collision_file([dask])	Reads in a collision history file and stores it as an Xarray Dataset in the collisions instance variable.
Simulation.follow([codestyle, dask])	An implementation of the Swift tool_follow algorithm.
Simulation.save([codename, param_file, ...])	Saves an xarray dataset to a set of input files.
Simulation.convert(param_file[, ...])	Converts simulation input files from one format to another (Swift, Swifter, or Swiftest).
Simulation.clean([deep])	Cleans up simulation directory by deleting old files (dump, logs, and output files).

Attributes

Simulation.param	A dictionary of simulation parameters.
Simulation.data	A dataset containing the simulation data.
Simulation.init_cond	A dataset containing the initial conditions.
Simulation.encounters	A dataset containing the encounter history
Simulation.collisions	A dataset containing the collision history.
Simulation.MU_name	The name of the mass unit currently defined in the simulation.
Simulation.DU_name	The name of the distance unit currently defined in the simulation.
Simulation.TU_name	The name of the time unit currently defined in the simulation.
Simulation.MU2KG	The conversion factor from mass unit to kilograms.
Simulation.KG2MU	The conversion factor from kilograms to mass unit.
Simulation.TU2S	The conversion factor from time unit to seconds.
Simulation.S2TU	The conversion factor from seconds to time unit.
Simulation.DU2M	The conversion factor from distance unit to meters.
Simulation.M2DU	The conversion factor from meters to distance unit.
Simulation.GU	The gravitational constant in the simulation units.
Simulation.integrator	The name of the integrator used in the simulation.
Simulation.codename	The name of the n-body code used in the simulation.
Simulation.simdir	The simulation directory.
Simulation.verbose	A boolean value indicating whether verbose output is enabled.
Simulation.ephemeris_date	ISO-formatted date sto use when obtaining the ephemerides in the format YYYY-MM-DD.
Simulation.restart	A boolean value indicating whether the run should be restarted from a previous output.

Data Representation

DataArray

SwiftestDataArray(*args, **kwargs)

N-dimensional xarray.DataArray-like array.

DataArray Methods

SwiftestDataArray.magnitude([name])	Computes the magnitude of a vector quantity.
SwiftestDataArray.rotate(rotation)	Rotates a vector quantity using a rotation matrix.

Dataset

SwiftestDataset(*args, **kwargs)

A xarray.Dataset-like, multi-dimensional, in memory, array database.

Dataset Methods

SwiftestDataset.rotate([rotvec, pole, skip_vars])	Rotates the coordinate system such that the z-axis is aligned with an input pole.
SwiftestDataset.xv2el([GMcb])	Converts A Dataset's Cartesian state vectors to orbital elements.
SwiftestDataset.el2xv([GMcb])	Converts a Dataset's orbital elements to Cartesian state vectors.

Initial Conditions Generation Functions

init_cond.get_solar_system_body(name[, ...])	Initializes a Swiftest dataset containing the major planets of the Solar System at a particular data from JPL/Horizons.
init_cond.horizons_query(id, ...[, ...])	Queries JPL/Horizons for a body matching the id.
init_cond.get_solar_system_body_mass_rotation(id)	Parses the raw output from JPL Horizons in order to extract physical properties of a body if they exist.

Gravitional Harmonics Functions

shgrav.clm_from_ellipsoid(mass, density, a)	Creates and returns the gravity coefficients for an ellipsoid with principal axes a, b, c upto a certain maximum degree lmax.
shgrav.clm_from_relief(mass, density, grid)	Creates and returns the gravity coefficients for a body with a given DH grid upto a certain maximum degree lmax.

Input/Output Processing Functions

A collection of functions for processing simulation files.

Reading and writing simulation parameter and initial conditions files

io.process_netcdf_input(ds, param)	Performs several tasks to convert raw NetCDF files output by the Fortran program into a form that is used by the Python side.
io.read_swiftest_param(param_file_name, param)	Reads in a Swiftest param.in file and saves it as a dictionary.
io.read_swifter_param(param_file_name[, verbose])	Reads in a Swifter param.in file and saves it as a dictionary.
io.read_swift_param(param_file_name[, ...])	Reads in a Swift param.in file and saves it as a dictionary.
io.write_swift_param(param, param_file_name)	Writes a Swift param.in file.
io.write_labeled_param(param, param_file_name)	Writes a Swifter/Swiftest param.in file.
io.select_active_from_frame(ds, param[, ...])	Selects a particular frame from a DataSet and returns only the active particles in that frame.
io.swiftest_xr2infile(ds, param[, in_type, ...])	Writes a set of Swiftest input files from a single frame of a Swiftest xarray dataset.

Tools for fixing differences between NetCDF-Fortran and xarray data structures

io.swiftest2xr(param[, verbose, dask])	Converts a Swiftest binary data file into an xarray DataSet.
io.reorder_dims(ds)	Re-order dimension coordinates so that they are in the same order as the Fortran side.
io.fix_types(ds[, itype, ftype])	Converts all variables in the dataset to the specified type.

Tools

Miscellaneous helper functions

tool.wrap_angle(angle)	Converts angles to be between 0 and 360 degrees.
tool.follow_swift(ds[, ifol, nskp])	Emulates the Swift version of tool_follow.f It will generate a file called follow.out containing 10 columns (angles are all in degrees).

Core

Compiled Fortran routines for the core of the Swiftest project.

core.driver(integrator, param_file_name, ...)
core.el2xv(mu, a, e, inc, capom, omega, capm)	Convert orbital elements to state vectors
core.xv2el(mu, rh, vh)	Convert state vectors to orbital elements

Constants

The constants module defines several astronomical and physical constants. Below is a description of each constant:

Constant	Description
GC	The gravitational constant (G) from Astropy constants, in SI units (m^3 kg^-1 s^-2).
AU2M	Astronomical Unit in meters, representing the average distance from the Earth to the Sun.
GMSun	Standard gravitational parameter for the Sun in m^3 s^-2.
MSun	Mass of the Sun in kilograms.
RSun	Radius of the Sun in meters.
MEarth	Mass of the Earth in kilograms.
REarth	Radius of the Earth in meters.
GMEarth	Standard gravitational parameter for the Earth in m^3 s^-2.
JD2S	Number of seconds in a Julian day.
YR2S	Number of seconds in a Julian year (365.25 days).
einsteinC	Speed of light in vacuum in meters per second.
J2Sun	Solar quadrupole moment coefficient (J2), indicating the extent of the Sun’s equatorial bulge.
J4Sun	Higher order coefficient (J4) for the Sun’s shape, indicating asymmetry in its mass distribution.
rotpoleSun	SkyCoord object representing the rotation pole of the Sun in right ascension (ra) and declination (dec), converted to Cartesian coordinates.
rotSun	Angular velocity of the Sun’s rotation in radians per second, considering an average rotational period of 25.05 days.

Fortran API Documentation

For detailed documentation of the Fortran API, see the Fortran API.