swiftest.Simulation

class swiftest.Simulation(simdir='simdata', param_file='param.in', read_param=False, read_data=False, read_init_cond=None, read_collisions=None, read_encounters=None, clean=False, dask=False, codename='Swiftest', integrator='symba', coarray=False, verbose=True, **kwargs)

Defines the basic Swift/Swifter/Swiftest simulation object.

__init__(simdir='simdata', param_file='param.in', read_param=False, read_data=False, read_init_cond=None, read_collisions=None, read_encounters=None, clean=False, dask=False, codename='Swiftest', integrator='symba', coarray=False, verbose=True, **kwargs)

Set up a new simulation object with the given parameters.

Parameters for a given Simulation object can be set a number of different ways, including via a parameter input file, arguments to Simulation, the general set_parameter method, or the specific setters for groups of similar parameters (e.g. set_init_cond_files, set_simulation_time, etc.). Each parameter has a default value that can be overridden by an argument to Simulation(). Some argument parameters have equivalent values that are passed to the Swiftest driver Fortran function via a parameter input file. When declaring a new Simulation object, parameters are chosen in the following way, from highest to lowest priority

1. Arguments to Simulation()

2. The parameter input file given by param_file under the following conditions

   • read_param is set to True (default behavior).

   • The file given by param_file exists. The default file is param.in located in the simdata directory inside the current working directory, which can be changed by passing param_file as an argument.

   • The argument has an equivalent parameter or set of parameters in the parameter input file.

3. Default values (see below)

Parameters:

• simdir (str, path-like, or None, default “simdata”) – The directory where the simulation data will be stored.

• param_file (str, path-like, or None, default “param.in”) – The name of the parameter input file that will be passed to the integrator. The parameter file should be located in the directory set by simdir. If the file does not exist, it will be created.

• read_param (bool, default True) – If true, read in a pre-existing parameter input file given by the argument param_file if it exists. Otherwise, create a new parameter file using the arguments passed to Simulation or defaults

• read_data (bool, default False) – If True, read in a pre-existing binary input file given by the argument output_file_name if it exists. If True, then read_param will also be set to True.

• read_init_cond (bool, default None) – If True, read in a pre-existing initial condition file given by the param.in parameter NC_IN or the argument init_cond_file_name if it exists. If None, then it will take the value of read_data. If True, then read_param will also be set to True

• read_collisions (bool, default None) – If True, read in a pre-existing collision file collisions.nc. If None, then it will take the value of read_data. If True, then read_param will also be set to True

• read_encounters (bool, default None) – If True, read in a pre-existing encounter file encounters.nc. If True, then read_param will also be set to True If None, then it will take the value of read_data.

• clean (bool, default False) – If True, then delete the simdir directory before initializing the simulation. If read_param is True, then this will be ignored.

• dask (bool, default False) – If true, will use Dask to lazily load data (useful for very large datasets).

• coarray (bool, default False) – If true, will employ Coarrays on test particle structures to run in single program/multiple data parallel mode. In order to use this capability, Swiftest must be compiled for Coarray support. Only certain integrators can use Coarrays. RMVS, WHM, Helio are all compatible, but SyMBA is not, due to the way tp-pl close encounters are handeled.

• verbose (bool, default False) – If set to True, then more information is printed by Simulation methods as they are executed. Setting to False suppresses most messages other than errors and some warnings.

• **kwargs (Any) – Any valid keyword arguments accepted by set_parameter() (see below)

Methods

__init__([simdir, param_file, read_param, ...])	Set up a new simulation object with the given parameters.
add_body([name, a, e, inc, capom, omega, ...])	Adds a body (test particle or massive body) to the internal Dataset given a set of either orbital elements or cartesian state vectors.
add_solar_system_body([name, ephemeris_id, ...])	Adds a solar system body to an existing simulation Dataset from the JPL Horizons ephemeris service.
clean([deep])	Cleans up simulation directory by deleting old files (dump, logs, and output files).
convert(param_file[, newcodename, plname, ...])	Converts simulation input files from one format to another (Swift, Swifter, or Swiftest).
follow([codestyle, dask])	An implementation of the Swift tool_follow algorithm.
get_distance_range([arg_list])	Returns a subset of the parameter dictionary containing the current values of the distance range parameters.
get_ephemeris_date([arg_list])	Prints the current value of the ephemeris date.
get_feature([arg_list])	Returns a subset of the parameter dictionary containing the current value of the feature boolean values.
get_init_cond_files([arg_list])	Returns a subset of the parameter dictionary containing the current initial condition file parameters.
get_integrator([arg_list])	Returns a subset of the parameter dictionary containing the current values of the distance range parameters.
get_output_files([arg_list])	Returns a subset of the parameter dictionary containing the current output file parameters.
get_parameter(**kwargs)	Setter for all possible parameters.
get_simulation_time([arg_list])	Returns a subset of the parameter dictionary containing the current simulation time parameters.
get_unit_system([arg_list])	Returns a subset of the parameter dictionary containing the current simulation unit system.
modify_body([name, id, a, e, inc, capom, ...])	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).
read_collision_file([dask])	Reads in a collision history file and stores it as an Xarray Dataset in the collisions instance variable.
read_encounter_file([dask])	Reads in an encounter history file and stores it as a SwiftestDataset in the encounters instance variable.
read_init_cond([init_cond_file_name, ...])	Reads in a set of initial conditions from file and stores them as the init_cond and data instance variables.
read_output_file([read_init_cond, ...])	Reads in simulation data from an output file and stores it as a SwiftestDataset in the data instance variable.
read_param([param_file, codename])	Reads in an input parameter file and stores the values in the param dictionary.
remove_body([name, id])	Removes a body (test particle or massive body) from the internal Dataset.
run([dask])	Runs a Swiftest integration.
save([codename, param_file, param, framenum])	Saves an xarray dataset to a set of input files.
set_distance_range([rmin, rmax, qmin_coord])	Sets the minimum and maximum distances of the simulation.
set_feature([close_encounter_check, ...])	Turns on or off various features of a simulation.
set_init_cond_files([init_cond_file_type, ...])	Sets the initial condition file parameters in the parameters dictionary.
set_integrator([codename, integrator, ...])	Sets the integrator to be used when running a simulation.
set_output_files([output_file_type, ...])	Sets the output file parameters in the parameter dictionary.
set_parameter(**kwargs)	Setter for all possible parameters.
set_simulation_time([t0, tstart, tstop, dt, ...])	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.
set_unit_system([MU, DU, TU, MU2KG, DU2M, ...])	Setter for setting the unit conversion between one of the standard sets.
write_param([codename, param_file, param])	Writes to a param.in file and determines whether the output format needs to be converted between Swift/Swifter/Swiftest.

Attributes

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