From d92ae434a8b88d759863a78ac9ee5fe365d7a4bc Mon Sep 17 00:00:00 2001 From: David Minton Date: Tue, 19 Dec 2023 16:19:15 -0500 Subject: [PATCH] Restructured documentation to be compatible with Sphinx. --- docs/Makefile | 4 +- docs/api.rst | 59 ++++ pyproject.toml | 1 + src/globals/globals_module.f90 | 16 +- swiftest/simulation_class.py | 499 ++++++++++++++++++--------------- 5 files changed, 347 insertions(+), 232 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 8b72a485d..803b51e0e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -61,13 +61,13 @@ fortran-doc: cd .. && ford fortran_docs.md .PHONY: html -html: fortran-doc +html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." .PHONY: rtdhtml -rtdhtml: fortran-doc +rtdhtml: $(SPHINXBUILD) -T -j auto -E -W --keep-going -b html -d $(BUILDDIR)/doctrees -D language=en . $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/docs/api.rst b/docs/api.rst index aa5bada49..9cad3b1d4 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -29,6 +29,65 @@ Running a Simulation Simulation.run +Setting Simulation Parameters +-------------------------------------------- + +.. autosummary:: + :toctree: generated/ + + Simulation.set_parameter + Simulation.set_simulation_time + Simulation.set_integrator + Simulation.set_feature + Simulation.set_init_cond_files + Simulation.set_output_files + Simulation.set_unit_system + Simulation.update_param_units + Simulation.set_distance_range + Simulation.set_ephemeris_date + +Retrieving Simulation Parameters +-------------------------------------------- + +.. autosummary:: + :toctree: generated/ + + Simulation.get_parameter + Simulation.get_simulation_time + Simulation.get_integrator + Simulation.get_feature + Simulation.get_init_cond_files + Simulation.get_output_files + Simulation.get_unit_system + Simulation.get_distance_range + Simulation.get_ephemeris_date + +Adding Bodies to a Simulation +----------------------------- + +.. autosummary:: + :toctree: generated/ + + Simulation.add_body + Simulation.add_solar_system_body + + +File Input and Output +--------------------- + +.. autosummary:: + :toctree: generated/ + + Simulation.read_param + Simulation.write_param + Simulation.read_encounter_file + Simulation.read_collision_file + Simulation.follow + Simulation.save + Simulation.initial_conditions_from_bin + Simulation.convert + Simulation.clean + Fortran API Documentation ========================= diff --git a/pyproject.toml b/pyproject.toml index 1961a87d2..70cfa62a3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -50,6 +50,7 @@ requires = [ "cmake", "pyproject_metadata", "pytest", + "pathspec", "sphinx", "sphinx-autosummary-accessors", "sphinx-book-theme >= 0.3.0", diff --git a/src/globals/globals_module.f90 b/src/globals/globals_module.f90 index 78a1ade9e..8bf98c6cd 100644 --- a/src/globals/globals_module.f90 +++ b/src/globals/globals_module.f90 @@ -1,11 +1,11 @@ -! Copyight 2022 - David Minton, Carlisle Wishard, Jennifer Pouplin, Jake Elliott, & Dana Singh -! This file is part of Swiftest. -! Swiftest is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License -! as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. -! Swiftest is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty -! of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. -! You should have received a copy of the GNU General Public License along with Swiftest. -! If not, see: https://www.gnu.org/licenses. +!! Copyright 2022 - David Minton, Carlisle Wishard, Jennifer Pouplin, Jake Elliott, & Dana Singh +!! This file is part of Swiftest. +!! Swiftest is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License +!! as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. +!! Swiftest is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty +!! of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. +!! You should have received a copy of the GNU General Public License along with Swiftest. +!! If not, see: https://www.gnu.org/licenses. module globals !! author: David A. Minton diff --git a/swiftest/simulation_class.py b/swiftest/simulation_class.py index 7df793a9c..09c8b1879 100644 --- a/swiftest/simulation_class.py +++ b/swiftest/simulation_class.py @@ -59,30 +59,32 @@ def __init__(self,read_param: bool = False, dask: bool = False, **kwargs: Any): """ - Set up a new simulation object. + 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 + + #. Arguments to Simulation() + #. 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. + + #. Default values (see below) Parameters ---------- 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 - - 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) 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. - Parameter input file equivalent: None + Parameter input file equivalent is None 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`. read_encounters : bool, default None @@ -90,232 +92,258 @@ def __init__(self,read_param: bool = False, simdir : PathLike, default `"simdir"` Directory where simulation data will be stored, including the parameter file, initial conditions file, output file, dump files, and log files. - - **kwargs : See list of valid parameters and their defaults below - + **kwargs : dict + See list of valid parameters and their defaults below codename : {"Swiftest", "Swifter", "Swift"}, default "Swiftest" Name of the n-body code that will be used. - Parameter input file equivalent: None + Parameter input file equivalent is None integrator : {"symba","rmvs","whm","helio"}, default "symba" Name of the n-body integrator that will be used when executing a run. - Parameter input file equivalent: None + Parameter input file equivalent is None read_param : bool, default False Read the parameter file given by `param_file`. param_file : str, path-like, or file-lke, default "param.in" Name of the parameter input file that will be passed to the integrator. - Parameter input file equivalent: None + Parameter input file equivalent is None t0 : float, default 0.0 The reference time for the start of the simulation. Defaults is 0.0. - Parameter input file equivalent: `T0` + Parameter input file equivalent is `T0` tstart : float, default 0.0 The start time for a restarted simulation. For a new simulation, tstart will be set to t0 automatically. - Parameter input file equivalent: `TSTART` + Parameter input file equivalent is `TSTART` tstop : float, optional The stopping time for a simulation. `tstop` must be greater than `tstart`. - Parameter input file equivalent: `TSTOP` + Parameter input file equivalent is `TSTOP` dt : float, optional The step size of the simulation. `dt` must be less than or equal to `tstop-tstart`. - Parameter input file equivalent: `DT` + Parameter input file equivalent is `DT` istep_out : int, optional - The number of time steps between output saves to file. *Note*: only `istep_out` or `tstep_out` can be set. - Parameter input file equivalent: `ISTEP_OUT` + The number of time steps between output saves to file. Only `istep_out` or `tstep_out` can be set. + Parameter input file equivalent is `ISTEP_OUT` tstep_out : float, optional - The approximate time between when outputs are written to file. Passing this computes - `istep_out = floor(tstep_out/dt)`. *Note*: only `istep_out` or `tstep_out` can be set. `tstep_out` must be less than `tstop` - Parameter input file equivalent: None + The approximate time between when outputs are written to file. + Passing this computes:: + + istep_out = floor(tstep_out/dt) + + Only `istep_out` or `tstep_out` can be set. `tstep_out` must be less than `tstop`. + Parameter input file equivalent is None nstep_out : int, optional - The total number of times that outputs are written to file. Passing this allows for a geometric progression of output steps: - `TSTART, f**0 * TSTEP_OUT, f**1 * TSTEP_OUT, f**2 * TSTEP_OUT, ..., f**(nstep_out-1) * TSTEP_OUT`, - where `f` is a factor that can stretch (or shrink) the time between outputs. Setting `nstep_out = int((tstart - tstop) / (tstep_out))` is - equivalent to the standard linear output (i.e. `f==1`) and is the same as not passing anything for this argument. - *Note*: Passing `nstep_out` requires passing either `istep_out` or `tstep_out` as well. + The total number of times that outputs are written to file. Passing this allows for a geometric progression of output + steps:: + + TSTART, f**0 * TSTEP_OUT, f**1 * TSTEP_OUT, f**2 * TSTEP_OUT, ..., f**(nstep_out-1) * TSTEP_OUT + + where `f` is a factor that can stretch (or shrink) the time between outputs. Setting:: + + nstep_out = int((tstart - tstop) / (tstep_out)) + + is equivalent to the standard linear output (i.e. `f==1`) and is the same as not passing anything for this argument. + Passing `nstep_out` requires passing either `istep_out` or `tstep_out` as well. dump_cadence : int, optional The number of output steps (given by `istep_out`) between when the saved data is dumped to a file. Setting it to 0 is equivalent to only dumping data to file at the end of the simulation. Default value is 10. - Parameter input file equivalent: `DUMP_CADENCE` + Parameter input file equivalent is `DUMP_CADENCE` init_cond_file_type : {"NETCDF_DOUBLE", "NETCDF_FLOAT", "ASCII"}, default "NETCDF_DOUBLE" - The file type containing initial conditions for the simulation: - * NETCDF_DOUBLE: A single initial conditions input file in NetCDF file format of type NETCDF_DOUBLE. - * NETCDF_FLOAT: A single initial conditions input file in NetCDF file format of type NETCDF_FLOAT. - * ASCII : Three initial conditions files in ASCII format. The individual files define the central body, + The file type containing initial conditions for the simulation. + + * "NETCDF_DOUBLE" A single initial conditions input file in NetCDF file format of type NETCDF_DOUBLE. + * "NETCDF_FLOAT" A single initial conditions input file in NetCDF file format of type NETCDF_FLOAT. + * "ASCII" Three initial conditions files in ASCII format. The individual files define the central body, + massive body, and test particle initial conditions. - Parameter input file equivalent: `IN_TYPE` + Parameter input file equivalent is `IN_TYPE` init_cond_file_name : str, path-like, or dict, optional Name of the input initial condition file or files. Whether to pass a single file name or a dictionary - depends on the argument passed to `init_cond_file_type`: If `init_cond_file_type={"NETCDF_DOUBLE","NETCDF_FLOAT"}`, - then this will be a single file name. If `init_cond_file_type="ASCII"` then this must be a dictionary where: - ```init_cond_file_name = { - "CB" : *path to central body initial conditions file* (Swiftest only), - "PL" : *path to massive body initial conditions file*, - "TP" : *path to test particle initial conditions file* - }``` + depends on the argument passed to `init_cond_file_type`. If `init_cond_file_type={"NETCDF_DOUBLE","NETCDF_FLOAT"}`, + then this will be a single file name. If `init_cond_file_type="ASCII"` then this must be a dictionary where:: + + init_cond_file_name = { + "CB" - [path to central body initial conditions file] (Swiftest only), + "PL" - [path to massive body initial conditions file], + "TP" - [path to test particle initial conditions file] } + If no file name is provided then the following default file names will be used. - * NETCDF_DOUBLE, NETCDF_FLOAT: `init_cond_file_name = "init_cond.nc"` - * ASCII: `init_cond_file_name = {"CB" : "cb.in", "PL" : "pl.in", "TP" : "tp.in"}` - Parameter input file equivalent: `NC_IN`, `CB_IN`, `PL_IN`, `TP_IN` + + * "NETCDF_DOUBLE", "NETCDF_FLOAT" `init_cond_file_name = "init_cond.nc"` + * "ASCII" `init_cond_file_name = {"CB" : "cb.in", "PL" : "pl.in", "TP" : "tp.in"}` + + Parameter input file equivalent is `NC_IN`, `CB_IN`, `PL_IN`, `TP_IN` init_cond_format : {"EL", "XV"}, default "EL" Indicates whether the input initial conditions are given as orbital elements or cartesian position and velocity vectors. - > *Note:* If `codename` is "Swift" or "Swifter", EL initial conditions are converted to XV. - Parameter input file equivalent: `IN_FORM` + If `codename` is "Swift" or "Swifter", EL initial conditions are converted to XV. + Parameter input file equivalent is `IN_FORM` output_file_type : {"NETCDF_DOUBLE", "NETCDF_FLOAT","REAL4","REAL8","XDR4","XDR8"}, default "NETCDF_DOUBLE" The file type for the outputs of the simulation. Compatible file types depend on the `codename` argument. - * Swiftest: Only "NETCDF_DOUBLE" or "NETCDF_FLOAT" supported. - * Swifter: Only "REAL4","REAL8","XDR4" or "XDR8" supported. - * Swift: Only "REAL4" supported. - Parameter input file equivalent: `OUT_TYPE` + + * Swiftest - Only "NETCDF_DOUBLE" or "NETCDF_FLOAT" supported. + * Swifter - Only "REAL4","REAL8","XDR4" or "XDR8" supported. + * Swift - Only "REAL4" supported. + + Parameter input file equivalent is `OUT_TYPE` output_file_name : str or path-like, optional Name of output file to generate. If not supplied, then one of the default file names are used, depending on the value passed to `output_file_type`. The default is "data.nc". - Parameter input file equivalent: `BIN_OUT` + Parameter input file equivalent is `BIN_OUT` output_format : {"XV","XVEL"}, default "XVEL" Specifies the format for the data saved to the output file. If "XV" then cartesian position and velocity vectors for all bodies are stored. If "XVEL" then the orbital elements are also stored. - Parameter input file equivalent: `OUT_FORM` + Parameter input file equivalent is `OUT_FORM` MU : str, default "MSUN" - The mass unit system to use. Case-insensitive valid options are: - * "Msun" : Solar mass - * "Mearth" : Earth mass - * "kg" : kilograms - * "g" : grams - Parameter input file equivalent: None + The mass unit system to use. Case-insensitive valid options are + + * "Msun" - Solar mass + * "Mearth" - Earth mass + * "kg" - kilograms + * "g" - grams + + Parameter input file equivalent is None DU : str, optional - The distance unit system to use. Case-insensitive valid options are: - * "AU" : Astronomical Unit - * "Rearth" : Earth radius - * "m" : meter - * "cm" : centimeter - Parameter input file equivalent: None + The distance unit system to use. Case-insensitive valid options are + + * "AU" - Astronomical Unit + * "Rearth" - Earth radius + * "m" - meter + * "cm" - centimeter + + Parameter input file equivalent is None TU : str, optional - The time unit system to use. Case-insensitive valid options are: - * "YR" : Year - * "DAY" : Julian day - * "d" : Julian day - * "JD" : Julian day - * "s" : second - Parameter input file equivalent: None - MU2KG: float, optional + The time unit system to use. Case-insensitive valid options are + + * "YR" - Year + * "DAY" - Julian day + * "d" - Julian day + * "JD" - Julian day + * "s" - second + + Parameter input file equivalent is None + MU2KG : float, optional The conversion factor to multiply by the mass unit that would convert it to kilogram. Setting this overrides MU - Parameter input file equivalent: `MU2KG` + Parameter input file equivalent is `MU2KG` DU2M : float, optional The conversion factor to multiply by the distance unit that would convert it to meter. Setting this overrides DU - Parameter input file equivalent: `DU2M` + Parameter input file equivalent is `DU2M` TU2S : float, optional The conversion factor to multiply by the time unit that would convert it to seconds. Setting this overrides TU - Parameter input file equivalent: `TU2S` + Parameter input file equivalent is `TU2S` MU_name : str, optional The name of the mass unit. When setting one of the standard units via `MU` a name will be automatically set for the unit, so this argument will override the automatic name. - Parameter input file equivalent: None + Parameter input file equivalent is None DU_name : str, optional The name of the distance unit. When setting one of the standard units via `DU` a name will be automatically set for the unit, so this argument will override the automatic name. - Parameter input file equivalent: None + Parameter input file equivalent is None TU_name : str, optional The name of the time unit. When setting one of the standard units via `TU` a name will be automatically set for the unit, so this argument will override the automatic name. - Parameter input file equivalent: None + Parameter input file equivalent is None rmin : float, default value is the radius of the Sun in the unit system defined by the unit input arguments. Minimum distance of the simulation - Parameter input file equivalent: `CHK_QMIN`, `CHK_RMIN`, `CHK_QMIN_RANGE[0]` + Parameter input file equivalent are `CHK_QMIN`, `CHK_RMIN`, `CHK_QMIN_RANGE[0]` rmax : float, default value is 10000 AU in the unit system defined by the unit input arguments. Maximum distance of the simulation (CHK_RMAX, CHK_QMIN_RANGE[1]) - Parameter input file equivalent: `CHK_RMAX`, `CHK_QMIN_RANGE[1]` + Parameter input file equivalent are `CHK_RMAX`, `CHK_QMIN_RANGE[1]` qmin_coord : str, {"HELIO", "BARY"}, default "HELIO" coordinate frame to use for checking the minimum periapsis distance - Parameter input file equivalent: `QMIN_COORD` + Parameter input file equivalent is `QMIN_COORD` mtiny : float, optional The minimum mass of fully interacting bodies. Bodies below this mass interact with the larger bodies, - but not each other (SyMBA only). *Note.* Only mtiny or gmtiny is accepted, not both. - Parameter input file equivalent: None + but not each other (SyMBA only). Only mtiny or gmtiny is accepted, not both. + Parameter input file equivalent is None gmtiny : float, optional The minimum G*mass of fully interacting bodies. Bodies below this mass interact with the larger bodies, - but not each other (SyMBA only). *Note.* Only mtiny or gmtiny is accepted, not both. - Parameter input file equivalent: `GMTINY` + but not each other (SyMBA only). Only mtiny or gmtiny is accepted, not both. + Parameter input file equivalent is `GMTINY` close_encounter_check : bool, default True Check for close encounters between bodies. If set to True, then the radii of massive bodies must be included in initial conditions. - Parameter input file equivalent: `CHK_CLOSE` + Parameter input file equivalent is `CHK_CLOSE` encounter_save : {"NONE","TRAJECTORY","CLOSEST", "BOTH"}, default "NONE" Indicate if and how encounter data should be saved. If set to "TRAJECTORY", the position and velocity vectors of all bodies undergoing close encounters are saved at each intermediate step to the encounter files. If set to "CLOSEST", the position and velocities at the point of closest approach between pairs of bodies are computed and stored to the encounter files. If set to "BOTH", then this stores the values that would be computed in "TRAJECTORY" and "CLOSEST". If set to "NONE" no trajectory information is saved. - *WARNING*: Enabling this feature could lead to very large files. + WARNING - Enabling this feature could lead to very large files. general_relativity : bool, default True - Include the post-Newtonian correction in acceleration calculations. - Parameter input file equivalent: `GR` - collision_model: {"MERGE","BOUNCE","FRAGGLE"}, default "MERGE" - This is used to set the collision/fragmentation model. [TODO: DESCRIBE THESE] - This argument only applies to Swiftest-SyMBA simulations. It will be ignored otherwise. - Parameter input file equivalent: `COLLISION_MODEL` + Include the post-Newtonian correction in acceleration calculations. + Parameter input file equivalent is "GR" + collision_model : {"MERGE","BOUNCE","FRAGGLE"}, default "MERGE" + This is used to set the collision/fragmentation model. + This argument only applies to Swiftest-SyMBA simulations and will be ignored otherwise. + Parameter input file equivalent is "COLLISION_MODEL" minimum_fragment_gmass : float, optional If fragmentation is turned on, this sets the mimimum G*mass of a collisional fragment that can be generated if a fragmentation model is enabled. Ignored otherwise. - *Note.* Only set one of minimum_fragment_gmass or minimum_fragment_mass - Parameter input file equivalent: None + Only set one of minimum_fragment_gmass or minimum_fragment_mass + Parameter input file equivalent is None minimum_fragment_mass : float, optional If fragmentation is turned on, this sets the mimimum mass of a collisional fragment that can be generated. if a fragmentation model is enabled. Ignored otherwise - *Note.* Only set one of minimum_fragment_gmass or minimum_fragment_mass - Parameter input file equivalent: `MIN_GMFRAG` + Only set one of minimum_fragment_gmass or minimum_fragment_mass + Parameter input file equivalent is `MIN_GMFRAG` nfrag_reduction : float, optional If fragmentation is turne don, this is a reduction factor used to limit the number of fragments generated in a collision. For instance, if the SFD of the collision would generated 300 fragments above the `minimum_fragment_mass`, then a value of `nfrag_reduction = 30.0` would reduce it to 10. - *Note.* Currently only used by the Fraggle collision model. + Currently only used by the Fraggle collision model. rotation : bool, default False If set to True, this turns on rotation tracking and radius, rotation vector, and moments of inertia values must be included in the initial conditions. This argument only applies to Swiftest-SyMBA simulations. It will be ignored otherwise. - Parameter input file equivalent: `ROTATION` + Parameter input file equivalent is `ROTATION` compute_conservation_values : bool, default False Turns on the computation of energy, angular momentum, and mass conservation and reports the values every output step of a running simulation. - Parameter input file equivalent: `ENERGY` + Parameter input file equivalent is `ENERGY` extra_force: bool, default False Turns on user-defined force function. - Parameter input file equivalent: `EXTRA_FORCE` + Parameter input file equivalent is `EXTRA_FORCE` big_discard: bool, default False Includes big bodies when performing a discard (Swifter only) - Parameter input file equivalent: `BIG_DISCARD` + Parameter input file equivalent is `BIG_DISCARD` rhill_present: bool, default False Include the Hill's radius with the input files . - Parameter input file equivalent: `RHILL_PRESENT` + Parameter input file equivalent is `RHILL_PRESENT` restart : bool, default False If true, will restart an old run. The file given by `output_file_name` must exist before the run can execute. If false, will start a new run. If the file given by `output_file_name` exists, it will be replaced when the run is executed. - Parameter input file equivalent: `OUT_STAT` + Parameter input file equivalent is `OUT_STAT` interaction_loops : {"TRIANGULAR","FLAT"}, default "TRIANGULAR" - > *Swiftest Experimental feature* + *Swiftest Experimental feature* Specifies which algorithm to use for the computation of body-body gravitational forces. - * "TRIANGULAR" : Upper-triangular double-loops . - * "FLAT" : Body-body interation pairs are flattened into a 1-D array. - Parameter input file equivalent: `INTERACTION_LOOPS` + + * "TRIANGULAR" - Upper-triangular double-loops. + * "FLAT" - Body-body interation pairs are flattened into a 1-D array. + + Parameter input file equivalent is `INTERACTION_LOOPS` encounter_check_loops : {"TRIANGULAR","SORTSWEEP"}, default "TRIANGULAR" - > *Swiftest Experimental feature* + *Swiftest Experimental feature* Specifies which algorithm to use for checking whether bodies are in a close encounter state or not. - * "TRIANGULAR" : Upper-triangular double-loops. - * "SORTSWEEP" : A Sort-Sweep algorithm is used to reduce the population of potential close encounter bodies. + + * "TRIANGULAR" - Upper-triangular double-loops. + * "SORTSWEEP" - A Sort-Sweep algorithm is used to reduce the population of potential close encounter bodies. This algorithm is still in development, and does not necessarily speed up the encounter checking. Use with caution. - Parameter input file equivalent: `ENCOUNTER_CHECK` + + Parameter input file equivalent is `ENCOUNTER_CHECK` dask : bool, default False 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. - *Note" 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 + 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 True 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. - Parameter input file equivalent: None + Parameter input file equivalent is None """ self._getter_column_width = 32 @@ -503,22 +531,30 @@ def set_simulation_time(self, dt : float, optional The step size of the simulation. `dt` must be less than or equal to `tstop-dstart`. istep_out : int, optional - The number of time steps between output saves to file. *Note*: only `istep_out` or `tstep_out` can be set. - Parameter input file equivalent: `ISTEP_OUT` + The number of time steps between output saves to file. Only `istep_out` or `tstep_out` can be set. + Parameter input file equivalent is `ISTEP_OUT` tstep_out : float, optional - The approximate time between when outputs are written to file. Passing this computes - `istep_out = floor(tstep_out/dt)`. *Note*: only `istep_out` or `tstep_out` can be set. - Parameter input file equivalent: None + The approximate time between when outputs are written to file. Passing this computes:: + + `istep_out = floor(tstep_out/dt)`. + + Only `istep_out` or `tstep_out` can be set. + Parameter input file equivalent is None nstep_out : int, optional The total number of times that outputs are written to file. Passing this allows for a geometric progression of output steps: - `TSTART, f**0 * TSTEP_OUT, f**1 * TSTEP_OUT, f**2 * TSTEP_OUT, ..., f**(nstep_out-1) * TSTEP_OUT`, - where `f` is a factor that can stretch (or shrink) the time between outputs. Setting `nstep_out = int((tstart - tstop) / (tstep_out))` is - equivalent to the standard linear output (i.e. `f==1`) and is the same as not passing anything for this argument. - *Note*: Passing `nstep_out` requires passing either `istep_out` or `tstep_out` as well. + + TSTART, f**0 * TSTEP_OUT, f**1 * TSTEP_OUT, f**2 * TSTEP_OUT, ..., f**(nstep_out-1) * TSTEP_OUT + + where `f` is a factor that can stretch (or shrink) the time between outputs. Setting:: + + nstep_out = int((tstart - tstop) / (tstep_out)) + + is equivalent to the standard linear output (i.e. `f==1`) and is the same as not passing anything for this argument. + Passing `nstep_out` requires passing either `istep_out` or `tstep_out` as well. dump_cadence : int, optional The number of output steps (given by `istep_out`) between when the saved data is dumped to a file. Setting it to 0 is equivalent to only dumping data to file at the end of the simulation. Default value is 10. - Parameter input file equivalent: `DUMP_CADENCE` + Parameter input file equivalent is `DUMP_CADENCE` verbose: bool, optional If passed, it will override the Simulation object's verbose flag **kwargs @@ -826,10 +862,10 @@ def set_integrator(self, Name of the n-body integrator that will be used when executing a run. mtiny : float, optional The minimum mass of fully interacting bodies. Bodies below this mass interact with the larger bodies, - but not each other (SyMBA only). *Note.* Only mtiny or gmtiny is accepted, not both. + but not each other (SyMBA only). Only mtiny or gmtiny is accepted, not both. gmtiny : float, optional The minimum G*mass of fully interacting bodies. Bodies below this mass interact with the larger bodies, - but not each other (SyMBA only). *Note.* Only mtiny or gmtiny is accepted, not both. + but not each other (SyMBA only). Only mtiny or gmtiny is accepted, not both. verbose: bool, optional If passed, it will override the Simulation object's verbose flag **kwargs @@ -999,28 +1035,27 @@ def set_feature(self, If set to "CLOSEST", the position and velocities at the point of closest approach between pairs of bodies are computed and stored to the encounter files. If set to "BOTH", then this stores the values that would be computed in "TRAJECTORY" and "CLOSEST". If set to "NONE" no trajectory information is saved. - *WARNING*: Enabling this feature could lead to very large files. + WARNING - Enabling this feature could lead to very large files. general_relativity : bool, optional Include the post-Newtonian correction in acceleration calculations. - collision_model: {"MERGE","BOUNCE","FRAGGLE"}, default "MERGE" - This is used to set the collision/fragmentation model. [TODO: DESCRIBE THESE] - This argument only applies to Swiftest-SyMBA simulations. It will be ignored otherwise. - Parameter input file equivalent: `COLLISION_MODEL` + collision_model : {"MERGE","BOUNCE","FRAGGLE"}, default "MERGE" + This is used to set the collision/fragmentation model. This argument only applies to Swiftest-SyMBA simulations. It + will be ignored otherwise. Parameter input file equivalent is `COLLISION_MODEL` minimum_fragment_gmass : float, optional If fragmentation is turned on, this sets the mimimum G*mass of a collisional fragment that can be generated if a fragmentation model is enabled. Ignored otherwise. - *Note.* Only set one of minimum_fragment_gmass or minimum_fragment_mass - Parameter input file equivalent: None + Only set one of minimum_fragment_gmass or minimum_fragment_mass + Parameter input file equivalent is None minimum_fragment_mass : float, optional If fragmentation is turned on, this sets the mimimum mass of a collisional fragment that can be generated. if a fragmentation model is enabled. Ignored otherwise - *Note.* Only set one of minimum_fragment_gmass or minimum_fragment_mass - Parameter input file equivalent: `MIN_GMFRAG` + Only set one of minimum_fragment_gmass or minimum_fragment_mass + Parameter input file equivalent is `MIN_GMFRAG` nfrag_reduction : float, optional If fragmentation is turne don, this is a reduction factor used to limit the number of fragments generated in a collision. For instance, if the SFD of the collision would generated 300 fragments above the `minimum_fragment_mass`, then a value of `nfrag_reduction = 30.0` would reduce it to 10. - *Note.* Currently only used by the Fraggle collision model. + Currently only used by the Fraggle collision model. rotation : bool, optional If set to True, this turns on rotation tracking and radius, rotation vector, and moments of inertia values must be included in the initial conditions. @@ -1037,18 +1072,22 @@ def set_feature(self, interaction_loops : {"TRIANGULAR","FLAT"}, default "TRIANGULAR" *Swiftest Experimental feature* Specifies which algorithm to use for the computation of body-body gravitational forces. + * "TRIANGULAR" : Upper-triangular double-loops . * "FLAT" : Body-body interation pairs are flattened into a 1-D array. + encounter_check_loops : {"TRIANGULAR","SORTSWEEP"}, default "TRIANGULAR" *Swiftest Experimental feature* Specifies which algorithm to use for checking whether bodies are in a close encounter state or not. + * "TRIANGULAR" : Upper-triangular double-loops. * "SORTSWEEP" : A Sort-Sweep algorithm is used to reduce the population of potential close encounter bodies. This algorithm is still in development, and does not necessarily speed up the encounter checking. Use with caution. + coarray : bool, default False If true, will employ Coarrays on test particle structures to run in single program/multiple data parallel mode. - *Note" In order to use this capability, Swiftest must be compiled for Coarray support. Only certain integrators + 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. tides: bool, optional @@ -1217,12 +1256,12 @@ def get_feature(self, arg_list: str | List[str] | None = None, verbose: bool | N Parameters ---------- - arg_list: str | List[str], optional + arg_list : str | List[str], optional A single string or list of strings containing the names of the features to extract. Default is all of: ["close_encounter_check", "general_relativity", "collision_model", "rotation", "compute_conservation_values"] - verbose: bool, optional + verbose : bool, optional If passed, it will override the Simulation object's verbose flag - **kwargs + **kwargs : Any A dictionary of additional keyword argument. This allows this method to be called by the more general get_parameter method, which takes all possible Simulation parameters as arguments, so these are ignored. @@ -1284,30 +1323,35 @@ def set_init_cond_files(self, Parameters ---------- init_cond_file_type : {"NETCDF_DOUBLE", "NETCDF_FLOAT", "ASCII"}, optional - The file type containing initial conditions for the simulation: + The file type containing initial conditions for the simulation + * NETCDF_DOUBLE: A single initial conditions input file in NetCDF file format of type NETCDF_DOUBLE * NETCDF_FLOAT: A single initial conditions input file in NetCDF file format of type NETCDF_FLOAT - * ASCII : Three initial conditions files in ASCII format. The individual files define the central body, - massive body, and test particle initial conditions. + * ASCII : Three initial conditions files in ASCII format. The individual files define the central body, massive body, and test particle initial conditions. + init_cond_file_name : str, path-like, or dict, optional Name of the input initial condition file or files. Whether to pass a single file name or a dictionary depends on the argument passed to `init_cond_file_type`: If `init_cond_file_type={"NETCDF_DOUBLE","NETCDF_FLOAT"}`, - then this will be a single file name. If `init_cond_file_type="ASCII"` then this must be a dictionary where: - ```init_cond_file_name = { - "CB" : *path to central body initial conditions file* (Swiftest only), - "PL" : *path to massive body initial conditions file*, - "TP" : *path to test particle initial conditions file* - }``` + then this will be a single file name. If `init_cond_file_type="ASCII"` then this must be a dictionary where:: + + init_cond_file_name = { + "CB" : *path to central body initial conditions file* (Swiftest only), + "PL" : *path to massive body initial conditions file*, + "TP" : *path to test particle initial conditions file* + } + If no file name is provided then the following default file names will be used. + * NETCDF_DOUBLE, NETCDF_FLOAT: `init_cond_file_name = "init_cond.nc"` * ASCII: `init_cond_file_name = {"CB" : "cb.in", "PL" : "pl.in", "TP" : "tp.in"}` + init_cond_format : {"EL", "XV"} Indicates whether the input initial conditions are given as orbital elements or cartesian position and velocity vectors. - > *Note:* If `codename` is "Swift" or "Swifter", EL initial conditions are converted to XV. - verbose: bool, optional + If `codename` is "Swift" or "Swifter", EL initial conditions are converted to XV. + verbose : bool, optional If passed, it will override the Simulation object's verbose flag - **kwargs + **kwargs : Any A dictionary of additional keyword argument. This allows this method to be called by the more general set_parameter method, which takes all possible Simulation parameters as arguments, so these are ignored. @@ -1424,9 +1468,9 @@ def get_init_cond_files(self, arg_list: str | List[str] | None = None, verbose: A single string or list of strings containing the names of the simulation time parameters to extract. Default is all of: ["init_cond_file_type", "init_cond_file_name", "init_cond_format"] - verbose: bool, optional + verbose : bool, optional If passed, it will override the Simulation object's verbose flag - **kwargs + **kwargs : Any A dictionary of additional keyword argument. This allows this method to be called by the more general get_parameter method, which takes all possible Simulation parameters as arguments, so these are ignored. @@ -1502,9 +1546,11 @@ def set_output_files(self, ---------- output_file_type : {"NETCDF_DOUBLE", "NETCDF_FLOAT","REAL4","REAL8","XDR4","XDR8"}, optional The file type for the outputs of the simulation. Compatible file types depend on the `codename` argument. + * Swiftest: Only "NETCDF_DOUBLE" or "NETCDF_FLOAT" supported. * Swifter: Only "REAL4","REAL8","XDR4" or "XDR8" supported. * Swift: Only "REAL4" supported. + output_file_name : str or path-like, optional Name of output file to generate. If not supplied, then one of the default file names are used, depending on the value passed to `output_file_type`. If one of the NetCDF types are used, the default is "data.nc". @@ -1512,11 +1558,11 @@ def set_output_files(self, output_format : {"XV","XVEL"}, optional Specifies the format for the data saved to the output file. If "XV" then cartesian position and velocity vectors for all bodies are stored. If "XVEL" then the orbital elements are also stored. - restart: bool, optional + restart : bool, optional Indicates whether this is a restart of an old run or a new run. - verbose: bool, optional + verbose : bool, optional If passed, it will override the Simulation object's verbose flag - **kwargs + **kwargs : Any A dictionary of additional keyword argument. This allows this method to be called by the more general set_parameter method, which takes all possible Simulation parameters as arguments, so these are ignored. @@ -1648,9 +1694,10 @@ def set_unit_system(self, """ Setter for setting the unit conversion between one of the standard sets. - The units can be set one of two ways: - 1) The user can supply string values to the arguments MU, DU, and TU to select between common systems - 2) The user can supply float values to the arguments MU2KG, DU2M, and TU2S to manually set the conversion + The units can be set one of two ways + + #. The user can supply string values to the arguments MU, DU, and TU to select between common systems + #. The user can supply float values to the arguments MU2KG, DU2M, and TU2S to manually set the conversion factor between the desired unit and the SI unit (kg-m-s). The two sets of arguments are mutually exclusive. Any values passed to MU2KG, DU2M, or TU2S will override any @@ -1659,24 +1706,30 @@ def set_unit_system(self, Parameters ---------- MU : str, optional - The mass unit system to use. Case-insensitive valid options are: - "Msun" : Solar mass - "Mearth" : Earth mass - "kg" : kilograms - "g" : grams + The mass unit system to use. Case-insensitive valid options are + + * "Msun" - Solar mass + * "Mearth" - Earth mass + * "kg" - kilograms + * "g" - grams + DU : str, optional - The distance unit system to use. Case-insensitive valid options are: - "AU" : Astronomical Unit - "Rearth" : Earth radius - "m" : meter - "cm" : centimeter + The distance unit system to use. Case-insensitive valid options are + + * "AU" - Astronomical Unit + * "Rearth" - Earth radius + * "m" - meter + * "cm" - centimeter + TU : str, optional - The time unit system to use. Case-insensitive valid options are: - "YR" : Year - "DAY" : Julian day - "d" : Julian day - "JD" : Julian day - "s" : second + The time unit system to use. Case-insensitive valid options are + + * "YR" - Year + * "DAY" - Julian day + * "d" - Julian day + * "JD" - Julian day + * "s" - second + MU2KG : float, optional The conversion factor to multiply by the mass unit that would convert it to kilogram. Setting this overrides MU @@ -1697,12 +1750,12 @@ def set_unit_system(self, automatically set for the unit, so this argument will override the automatic name. recompute_unit_values : bool, default True Recompute all values into the new unit system. - >*Note:* This is a destructive operation, however if not executed then the values contained in the parameter - > file and input/output data files computed previously may not be consistent with the new unit conversion - > factors. - verbose: bool, optional + This is a destructive operation, however if not executed then the values contained in the parameter + file and input/output data files computed previously may not be consistent with the new unit conversion + factors. + verbose : bool, optional If passed, it will override the Simulation object's verbose flag - **kwargs + **kwargs : Any A dictionary of additional keyword argument. This allows this method to be called by the more general set_parameter method, which takes all possible Simulation parameters as arguments, so these are ignored. @@ -1836,9 +1889,8 @@ def get_unit_system(self, arg_list: str | List[str] | None = None, verbose: bool ---------- arg_list : str | List[str], optional A single string or list of strings containing the names of the simulation unit system - Default is all of: - ["MU", "DU", "TU"] - **kwargs + Default is all of ["MU", "DU", "TU"] + **kwargs : Any A dictionary of additional keyword argument. This allows this method to be called by the more general get_parameter method, which takes all possible Simulation parameters as arguments, so these are ignored. @@ -1898,9 +1950,12 @@ def update_param_units(self, MU2KG_old, DU2M_old, TU2S_old): Parameters ---------- - MU2KG_old : Old value of the mass unit conversion factor - DU2M_old : Old value of the distance unit conversion factor - TU2S_old : Old value of the time unit conversion factor + MU2KG_old : float + Old value of the mass unit conversion factor + DU2M_old : float + Old value of the distance unit conversion factor + TU2S_old : float + Old value of the time unit conversion factor Returns ------- @@ -1953,7 +2008,7 @@ def set_distance_range(self, Maximum distance of the simulation (CHK_RMAX, CHK_QMIN_RANGE[1]) qmin_coord : str, {"HELIO", "BARY"} coordinate frame to use for CHK_QMIN - **kwargs + **kwargs : Any A dictionary of additional keyword argument. This allows this method to be called by the more general set_parameter method, which takes all possible Simulation parameters as arguments, so these are ignored. @@ -2006,11 +2061,10 @@ def get_distance_range(self, arg_list: str | List[str] | None = None, verbose: b Parameters ---------- arg_list: str | List[str], optional - A single string or list of strings containing the names of the features to extract. Default is all of: - ["rmin", "rmax"] + A single string or list of strings containing the names of the features to extract. Default is all of ["rmin", "rmax"] verbose: bool, optional If passed, it will override the Simulation object's verbose flag - **kwargs + **kwargs : Any A dictionary of additional keyword argument. This allows this method to be called by the more general get_parameter method, which takes all possible Simulation parameters as arguments, so these are ignored. @@ -2092,9 +2146,10 @@ def add_solar_system_body(self, set by `set_ephemeris_date`. source : str, default "Horizons" The source of the ephemerides. - >*Note.* Currently only the JPL Horizons ephemeris is implemented, so this is ignored. - **kwargs: Any + Currently only the JPL Horizons ephemeris is implemented, so this is ignored. + **kwargs : Any Additional keyword arguments to pass to the query method (i.e. astroquery.Horizons) + Returns ------- None @@ -2197,9 +2252,9 @@ def set_ephemeris_date(self, ephemeris_date : str, optional Date to use when obtaining the ephemerides. Valid options are "today", "MBCL", or date in the format YYYY-MM-DD. - verbose: bool, optional + verbose : bool, optional If passed, it will override the Simulation object's verbose flag - **kwargs + **kwargs : Any A dictionary of additional keyword argument. This allows this method to be called by the more general set_parameter method, which takes all possible Simulation parameters as arguments, so these are ignored. @@ -2336,43 +2391,43 @@ def add_body(self, Parameters ---------- name : str or array-like of str, optional - Name or names of Bodies. If none passed, name will be "Body" + Name or names of Bodies. If none passed, name will be "Body" id : int or array-like of int, optional - Unique id values. If not passed, an id will be assigned in ascending order starting from the pre-existing - Dataset ids. + Unique id values. If not passed, an id will be assigned in ascending order starting from the pre-existing + Dataset ids. a : float or array-like of float, optional - semimajor axis for param['IN_FORM'] == "EL" + semimajor axis for param['IN_FORM'] == "EL" e : float or array-like of float, optional - eccentricity for param['IN_FORM'] == "EL" + eccentricity for param['IN_FORM'] == "EL" inc : float or array-like of float, optional - inclination for param['IN_FORM'] == "EL" + inclination for param['IN_FORM'] == "EL" capom : float or array-like of float, optional - longitude of ascending node for param['IN_FORM'] == "EL" + longitude of ascending node for param['IN_FORM'] == "EL" omega : float or array-like of float, optional - argument of periapsis for param['IN_FORM'] == "EL" + argument of periapsis for param['IN_FORM'] == "EL" capm : float or array-like of float, optional - mean anomaly for param['IN_FORM'] == "EL" + mean anomaly for param['IN_FORM'] == "EL" rh : (n,3) array-like of float, optional - Position vector array. + Position vector array. vh : (n,3) array-like of float, optional - Velocity vector array. + Velocity vector array. mass : float or array-like of float, optional - mass values if these are massive bodies (only one of mass or Gmass can be passed) + mass values if these are massive bodies (only one of mass or Gmass can be passed) Gmass : float or array-like of float, optional - G*mass values if these are massive bodies (only one of mass or Gmass can be passed) + G*mass values if these are massive bodies (only one of mass or Gmass can be passed) radius : float or array-like of float, optional - Radius values if these are massive bodies + Radius values if these are massive bodies rhill : float or array-like of float, optional - Hill's radius values if these are massive bodies + Hill's radius values if these are massive bodies rot: (3) or (n,3) array-like of float, optional - Rotation rate vectors if these are massive bodies with rotation enabled. + Rotation rate vectors if these are massive bodies with rotation enabled. Ip: (3) or (n,3) array-like of float, optional - Principal axes moments of inertia vectors if these are massive bodies with rotation enabled. + Principal axes moments of inertia vectors if these are massive bodies with rotation enabled. Returns ------- data : Xarray Dataset - Dasaset containing the body or bodies that were added + Dasaset containing the body or bodies that were added """