diff --git a/docs/user-guide/basic-simulation/index.rst b/docs/user-guide/basic-simulation/index.rst index 5958406e7..7b8d34463 100644 --- a/docs/user-guide/basic-simulation/index.rst +++ b/docs/user-guide/basic-simulation/index.rst @@ -79,6 +79,12 @@ file. The default value is 10, which means that Swiftest will store 10 outputs i Setting ``dump_cadence`` to 0 is a a special case that tells Swiftest to store *all* output in memory until the end of the simulation. This is useful for short simulations, but can be memory intensive for long simulations. +.. note:: + Changing the value of ``dump_cadence`` does not change the amount of data that is output by the end of the simulation. It only + changes how often the data is written to disk. Changing the value of ``tstep_out`` (or ``istep_out``) *does* change the amount of + data that is output by the end of the simulation. Intermediate steps between output steps are not saved to disk, and cannot be + recovered after the simulation has finished. + The choice of what values to set for ``tstep_out`` (or ``istep_out``), ``nstep_out``, and ``dump_cadence`` depends on the particular simulation. Higher values of ``dump_cadence`` are typically useful for simulations with small numbers of bodies and small values of ```tstep_out`` where frequent writing to disk can severely impact performance. For simulations with large numbers of bodies and @@ -87,10 +93,10 @@ so that the memory usage does not become too large. The default value of ``dump_ caes. We can set these simulation parameters using the :func:`set_parameter ` method. -Here we have a simulation that runs for 1 My a step size of 0.01 y. We will also save the system every 1000 y and wait until the end +Here we have a simulation that runs for 100,000 y a step size of 0.01 y. We will also save the system every 1000 y and wait until the end of the simulation to write the simulation data to file using the ``dump_cadence=0`` argument:: - sim.set_parameter(tstop=1.0e6, tstep_out=1e3, dt=0.01, dump_cadence=0) + sim.set_parameter(tstop=1.0e5, tstep_out=1e3, dt=0.01, dump_cadence=0) Once everything is set up, we call the :func:`run ` method to integrate the system forward in time:: @@ -99,7 +105,7 @@ Once everything is set up, we call the :func:`run ` met Swiftest is relatively flexible with arguments. You can pass the parameters in when initializing the simulation object, or even later when running. So the following are all equivalent:: - sim = swiftest.Simulation(tstop=1.0e6, tstep_out=1e3, dt=0.01, dump_cadence=0) + sim = swiftest.Simulation(tstop=1.0e5, tstep_out=1e3, dt=0.01, dump_cadence=0) sim.add_solar_system_body(["Sun","Mercury","Venus","Earth","Mars","Jupiter","Saturn","Uranus","Neptune"]) sim.run() @@ -110,7 +116,7 @@ So the following are all equivalent:: sim = swiftest.Simulation() sim.add_solar_system_body(["Sun","Mercury","Venus","Earth","Mars","Jupiter","Saturn","Uranus","Neptune"]) - sim.run(tstop=1.0e6, tstep_out=1e3, dt=0.01, dump_cadence=0) + sim.run(tstop=1.0e5, tstep_out=1e3, dt=0.01, dump_cadence=0) .. note:: Swiftest uses OpenMP parallelization to help speed up the integration, however the parallelization is most effective when there @@ -131,6 +137,57 @@ Once a simulation has been run, its output data is stored in the ``./simdata`` d default name of ``data.nc``, which is a netCDF file. It is read in and stored as an `Xarray Dataset `__ object in the ``sim.data`` attribute. +Here is an example of what the dataset looks like after the above simulation has been run:: + + In [8]: sim.data + Out[8]: + Size: 229kB + + Dimensions: (time: 101, space: 3, name: 9) + Coordinates: + * time (time) float64 808B 0.0 1e+03 2e+03 ... 9.9e+04 1e+05 + * space (space)