Merge branch '4-write-a-basic-test-simulation-and-user-guide-for-sphe…

…rical-harmonics-use' into debug

.github/workflows/build_wheels.yml

@@ -6,6 +6,9 @@ on:
   push:
     branches:
       - master
+  release:
+    types:
+      - published
 
 jobs:
   build_wheels:
@@ -48,7 +51,7 @@ jobs:
       url: https://pypi.org/p/swiftest
     permissions:
       id-token: write
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    if: github.event_name == 'release' && github.event.action == 'published'
     steps:
       - uses: actions/download-artifact@v4
         with:

docs/user-guide/basic-simulation/index.rst → docs/user-guide/basic-simulation.rst

@@ -2,6 +2,8 @@
 Basic Simulation
 #################
 
+.. rubric:: by David A. Minton
+
 Here, we will walk you through the basic features of Swiftest and using them in Python. 
 
 Start with importing Swiftest. ::
@@ -196,7 +198,7 @@ Here is an example where we can generate a simple plot of the semimajor axis vs.
 
   sim.data['a'].where(sim.data.particle_type != 'Central Body', drop=True).plot(x='time',hue='name')
 
-.. image:: ../../_static/basic_simulation_a_vs_t_plot.png
+.. image:: ../_static/basic_simulation_a_vs_t_plot.png
 
 This is just a simple example of what you can do with the simulation data. Xarray has a large number of built-in plotting and 
 data processing functions. For more information, see the `Xarray documentation <https://docs.xarray.dev/en/stable/>`__.

docs/user-guide/detailed-simulation-setup/index.rst → docs/user-guide/detailed-simulation-setup.rst

@@ -2,6 +2,8 @@
 Detailed Simulation
 #####################
 
+.. rubric:: by Kaustub Anand
+
 Here, we will walk you through the basic features of Swiftest and using them in Python. 
 This is based on ``/Basic_Simulation`` in ``swiftest/examples``.
 
@@ -31,7 +33,7 @@ The biggest body in the simulation is taken as the central body.
 Solar System Bodies
 =========================
 
-We can add solar system bodies to the simulation using the ``add_solar_system_body`` method. 
+We can add solar system bodies to the simulation using the :func:`add_solar_system_body <swiftest.Simulation.add_solar_system_body>` method. 
 This method uses JPL Horizons to extract the parameters. ::
    
    # Add the modern planets and the Sun using the JPL Horizons Database.
@@ -51,8 +53,8 @@ We can add other small bodies too. ::
 User Defined Bodies
 =========================
 
-For completeness, let's also add some bodies with user defined parameters using ``sim.add_body()``.
-We will randomize the initial conditions and therefore import the ``numpy.random`` module.::
+For completeness, let's also add some bodies with user defined parameters using :func:`sim.add_body <swiftest.Simulation.add_body>`.
+We will randomize the initial conditions and therefore import the `numpy.random <https://numpy.org/doc/stable/reference/random/index.html#module-numpy.random>`__ module.::
 
    from numpy.random import default_rng
    rng = default_rng(seed=123)
@@ -88,7 +90,7 @@ Initialize orbital elements and then add the bodies. ::
 Cartesian Coordinates
 ----------------------
 
-The process is similar for adding bodies with Cartesian coordinates. However, the parameter `init_cond_format` must be set to `XV` before adding the bodies.
+The process is similar for adding bodies with cartesian coordinates. However, the parameter `init_cond_format` must be set to `XV` before adding the bodies.
 The process of setting parameters is explained in the next section. 
 Start by defining the position and velocity vectors. Here we define the orbital velocities and scale them by a random value. ::
    
@@ -113,7 +115,7 @@ Start by defining the position and velocity vectors. Here we define the orbital
 
    sim.add_body(name=name_pl, rh=rh_pl, vh=vh_pl, mass=M_pl, radius=R_pl,  Ip=Ip_pl, rot=rot_pl)
 
-The process is similar for **test particles**. The only difference is to exclude ``mass`` and ``radius``. 
+The process is similar for **test particles**. They only need the orbital elements or the cartesian coordinates. 
 Here is an example with orbital elements: ::
 
     # Add 10 user-defined test particles.
@@ -141,16 +143,16 @@ This can be done in multiple ways:
     sim = swiftest.Simulation(simdir = simdir, integrator = 'symba', init_cond_format = 'EL', tstart=0.0, tstop=1.0e6, dt=0.01, 
                                 istep_out=100, dump_cadence=0, compute_conservation_values=True, mtiny=mtiny)
     
-- ``sim.set_parameter()``: Set individual parameters in the simulation. The user can set one or multiple at a time. ::
+- :func:`sim.set_parameter <swiftest.Simulation.set_parameter>`: Set individual parameters in the simulation. The user can set one or multiple at a time. ::
 
     sim.set_parameter(tstart=0.0, tstop=1.0e6, dt=0.01, istep_out=100, dump_cadence=0, compute_conservation_values=True, mtiny=mtiny)
     sim.set_parameter(rmin = 0.05)
 
 We now set up the simulation parameters. Here we have a simulation starting from `0.0 y` and running for `1 My = 1e6 years` 
 with time steps of `0.01 years`. The timestep should be less than or equal to 1/10 of the orbital period of the innermost body. 
 
-The user can then write the parameters to the `param.in` file by using ``sim.write_param()``.
-To see the parameters of the simulation, use ``sim.get_parameter()``.
+The user can then write the parameters to the `param.in` file by using :func:`write_param <swiftest.Simulation.write_param>`.
+To see the parameters of the simulation, use :func:`sim.get_parameter <swiftest.Simulation.get_parameter>`.
 
 Running the Simulation
 ========================

docs/user-guide/gravitational-harmonics/index.rst → docs/user-guide/gravitational-harmonics.rst

@@ -2,10 +2,12 @@
 Gravitational Harmonics
 ##########################
 
-Here, we show how to use Swiftest's Gravitational Harmonics capabilities. This is based on ``/spherical_harmonics_cb`` 
+.. rubric:: by Kaustub Anand
+
+Here, we show how to use Swiftest's Gravitational Harmonics capabilities. This is based on ``spherical_harmonics_cb`` 
 in ``swiftest/examples``. Swiftest uses `SHTOOLS <https://shtools.github.io/SHTOOLS/>`__ to compute the gravitational 
-harmonics coefficients for a given body and calculate it's associated acceleration kick. The conventions and formulae used 
-to calculate the additional kick are described `here <https://sseh.uchicago.edu/doc/Weiczorek_2015.pdf>`__. The gravitational
+harmonics coefficients for a given body and calculate it's associated acceleration kick. The conventions and formulae used here 
+are described in `Weiczorek et al. (2015) <https://sseh.uchicago.edu/doc/Weiczorek_2015.pdf>`__. The gravitational
 potential is given by the following equation:
 
 .. math::
@@ -40,7 +42,7 @@ The coefficients can be computed in a number of ways:
 
 - Manually entering the coefficients when adding the central body. (:func:`add_body <swiftest.Simulation.add_body>`)
 
-Computing coefficients from axes measurements
+Computing Coefficients from Axes Measurements
 ===============================================
 
 Given the axes measurements of a body, the gravitational harmonics coefficients can be computed in a straightforward 
@@ -59,19 +61,19 @@ manner. Here we use Chariklo as an example body and refer to Jacobi Ellipsoid mo
     cb_T_rotation/= 24.0 # converting to julian days (TU)
     cb_rot = [[0, 0, 360.0 / cb_T_rotation]] # degrees/TU
 
-Once the central body parameters are defined, we can compute the gravitational harmonics coefficients (:math:`C_{lm}`). Here we set the 
-reference radius flag to `True` and ask the function to return the reference radius. More in the additional capabilities section below.
+Once the central body parameters are defined, we can compute the gravitational harmonics coefficients (:math:`C_{lm}`).
 The output coefficients are already correctly normalized. ::
 
     c_lm, cb_radius = swiftest.clm_from_ellipsoid(mass = cb_mass, density = cb_density, a = cb_a, b = cb_b, c = cb_c, lref_radius = True)
 
-*Note: The maximum degree is set to 6 by default to ensure computational efficiency.*
+*Note: Here we set the reference radius flag to* `True` *and ask the function to return the reference radius. More in the 
+additional capabilities section below. The maximum degree is set to 6 by default to ensure computational efficiency.*
 
 Add the central body to the simulation along with the coefficients. ::
 
     sim.add_body(name = 'Chariklo', mass = cb_mass, rot = cb_rot, radius = cb_radius, c_lm = c_lm)
 
-If the :math:`J2` and :math:`J4` terms are passed as well, Swiftest ignores them and uses the :math:`C_{lm}` terms instead.
+If the :math:`J_{2}` and :math:`J_{4}` terms are passed as well, Swiftest ignores them and uses the :math:`C_{lm}` terms instead.
 Now the user can set up the rest of the simulation as usual. ::
 
     # add other bodies and set simulation parameters
@@ -82,17 +84,32 @@ Now the user can set up the rest of the simulation as usual. ::
     # run the simulation
     sim.run()
 
+Manually Adding the Coefficients
+================================
+
+If the user already has the coefficients, they can be added to the central body directly. Ensure that they are correctly normalized and 
+the right shape. The dimensions of ``c_lm`` is ``[sign, l, m]`` where: 
+
+- ``sign`` indicates coefficients of positive (``[0]``) and negative (``[1]``) ``m`` and is of length 2. 
+- The dimension ``l`` corresponds to the degree of the Spherical Harmonic and is of length :math:`l_{max} + 1`.
+- The dimension ``m`` corresponds to the order of the Spherical Harmonic and is of length :math:`l_{max} + 1`.
+
+:math:`l_{max}` is the highest order of the coefficients. ::
+
+    c_lm = ..... # defined by the user
+    sim.add_body(name = 'Body', mass = cb_mass, rot = cb_rot, radius = cb_radius, c_lm = c_lm)
+
 Additional Capabilities of Swiftest's Coefficient Generator Functions
 ===========================================================================================
 
 The output from :func:`clm_from_ellipsoid <swiftest.shgrav.clm_from_ellipsoid>` and :func:`clm_from_relief <swiftest.shgrav.clm_from_relief>`
 can be customised to the user's needs. Here we show some of the additional capabilities of these functions.
 
-Setting a reference radius for the coefficients
+Setting a Reference Radius for the Coefficients
 -------------------------------------------------
 
 The coefficients are computed with respect to a reference radius. `SHTOOLS <https://shtools.github.io/SHTOOLS/>`__ calculates it's own radius from 
-the axes passed, but there are difference ways to calculate the reference radius for non-spherical bodies in the literature. As a result, Swiftest allows 
+the axes passed, but there are different ways to calculate the reference radius for non-spherical bodies in the literature. As a result, Swiftest allows 
 the user to explicitly set a reference radius (``ref_radius``) which scales the coefficients accordingly. This is particularly useful when a 
 specific radius is desired.
 
@@ -111,7 +128,7 @@ By default, ``lref_radius`` is set to ``False``. In this case, the function only
 
     c_lm = swiftest.clm_from_ellipsoid(mass = cb_mass, density = cb_density, a = cb_a, b = cb_b, c = cb_c)
 
-We recommend extracting the ``ref_radius`` from the function output and using it accordingly.
+We recommend extracting the ``ref_radius`` from the function output and using it when adding the central body to the simulation.
 
 Combinations of Principal Axes
 -------------------------------
@@ -150,41 +167,3 @@ characteristic wavelength (:math:`\lambda`) of a harmonic degree (:math:`l`) to
     \lambda = \frac{2\pi R}{\sqrt{l(l+1)}} 
 
     \lambda = R \Rightarrow l = 6
-
-.. Final Steps for Running the Simulation
-.. =======================================
-
-.. Add other bodies to the simulation. ::
-
-..     # Add user-defined massive bodies
-..     npl         = 5
-..     density_pl  = cb_density
-
-..     name_pl     = ["SemiBody_01", "SemiBody_02", "SemiBody_03", "SemiBody_04", "SemiBody_05"]
-..     a_pl        = rng.uniform(250, 400, npl)
-..     e_pl        = rng.uniform(0.0, 0.05, npl)
-..     inc_pl      = rng.uniform(0.0, 10, npl)
-..     capom_pl    = rng.uniform(0.0, 360.0, npl)
-..     omega_pl    = rng.uniform(0.0, 360.0, npl)
-..     capm_pl     = rng.uniform(0.0, 360.0, npl)
-..     R_pl        = np.array([0.5, 1.0, 1.2, 0.75, 0.8])
-..     M_pl        = 4.0 / 3 * np.pi * R_pl**3 * density_pl
-..     Ip_pl       = np.full((npl,3),0.4,)
-..     rot_pl      = np.zeros((npl,3))
-..     mtiny       = 1.1 * np.max(M_pl)
-
-..     sim.add_body(name=name_pl, a=a_pl, e=e_pl, inc=inc_pl, capom=capom_pl, omega=omega_pl, capm=capm_pl, mass=M_pl, radius=R_pl,  Ip=Ip_pl, rot=rot_pl)
-
-.. Set the parameters for the simulation and run. ::
-
-..     sim.set_parameter(tstart=0.0, tstop=10.0, dt=0.01, istep_out=10, dump_cadence=0, compute_conservation_values=True, mtiny=mtiny)
-
-..     # Run the simulation
-..     sim.run()
-
-
-
-
-.. .. toctree::
-..    :maxdepth: 2
-..    :hidden:

docs/user-guide/index.rst

@@ -4,16 +4,16 @@ User Guide
 
 In this user guide, you will find detailed descriptions and examples that describe the many capabilities of Swiftest and how to use them.
 
-- Setting up a :doc:`Basic Simulation <basic-simulation/index>`
+- Setting up a :doc:`Basic Simulation <basic-simulation>`
 
-- A more in-depth :doc:`Detailed Simulation Setup <detailed-simulation-setup/index>`
+- A more in-depth :doc:`Detailed Simulation Setup <detailed-simulation-setup>`
 
-- Understanding the :doc:`Gravitational Harmonics capabilities <gravitational-harmonics/index>`
+- Understanding the :doc:`Gravitational Harmonics capabilities <gravitational-harmonics>`
 
 .. toctree::
    :maxdepth: 2
    :hidden:
 
-   Basic Simulation <basic-simulation/index>
-   Detailed Simulation Setup <detailed-simulation-setup/index>
-   Gravitational Harmonics <gravitational-harmonics/index>
+   Basic Simulation <basic-simulation>
+   Detailed Simulation Setup <detailed-simulation-setup>
+   Gravitational Harmonics <gravitational-harmonics>